Developer Report Retrieval

1. Overview

The Carty Developer Platform provides the Developer Report Retrieval API, allowing developers to fetch report data via a server-side interface.
The API supports date-based statistics and paginated responses, making it convenient for data analysis, revenue reconciliation, and operational monitoring.

---

2. API Information

• API Name: Developer Report Retrieval
• Endpoint: /api/report/out-search
• HTTP Method: POST
• Encoding: UTF-8
• Content-Type: application/json

2.1 Domain

• Production Environment:
  https://developer.gocarty.net/

• Full Request URL Example:

  https://developer.gocarty.net/api/report/out-search

---

3. Authentication (Authorization)

This API uses API Key authentication.

• Request Header: Authorization
• Example Value: rk_0jmtmwkz8grugecy1bp7syh4e6wgg41a
• How to Obtain: Retrieve it from the apikeys module in the system dashboard

⚠️ Please keep your API Key secure and do not expose it in public repositories.

---

4. Request Parameters

4.1 Header Parameters

Parameter	Required	Type	Description
Authorization	Yes	String	API Key
Content-Type	Yes	String	Must be application/json

---

4.2 Body Parameters (JSON)

Parameter	Required	Type	Description
start_date	Yes	String	Start date, format: YYYY-MM-DD
end_date	Yes	String	End date, format: YYYY-MM-DD (must be ≥ start_date)
group	Yes	Array	Grouping fields, e.g., ["date", "os", "app_id", "ad_type", "placement_id", "country"]
page	Yes	Int	Page number, default is 1
page_size	Yes	Int	Number of records per page, default is 10

remarks:

• a. Obtain daily data, with a maximum time span of 7 days

Request Example

{
  "start_date": "2026-02-01",
  "end_date": "2026-02-07",
  "group": [
    "date",
    "os",
    "app_id",
    "ad_type",
    "placement_id",
    "country"
  ],
  "page": 1,
  "page_size": 10
}

---

5. Response Parameters

5.1 Response Structure

Field	Type	Description
code	Int	Status code: 0 indicates success, non-0 indicates failure
message	String	Response message
data	Object	Data object

---

5.2 data.list Fields

Field	Type	Description
date	String	Date (YYYY-MM-DD)
bid_type	Int	Bid type
request	Int	Number of requests
fill	Int	Number of fills
impression	Int	Number of impressions
click	Int	Number of clicks
revenue	Number	Developer revenue
ctr	Number	Click-through rate (%)
ecpm	Number	eCPM
ecpc	Number	eCPC
fill_rate	Number	Fill rate (%)
impression_rate	Number	Impression rate (%)
summary	Object	Summary data

---

5.3 data.page Fields

Field	Type	Description
current	Int	Current page
page_size	Int	Records per page
total	Int	Total records

---

6. Response Example

{
    "code": 0,
    "message": "success",
    "data": {
        "list": [
            {
                "date": "2026-02-06",
                "request": 541,
                "fill": 539,
                "impression": 365,
                "click": 44,
                "revenue": 4.91,
                "ctr": 0.12,
                "ecpm": 13.45,
                "ecpc": 0.11,
                "fill_rate": 1,
                "impression_rate": 0.68
            },
            {
                "date": "2026-02-05",
                "request": 40,
                "fill": 35,
                "impression": 25,
                "click": 6,
                "revenue": 1.28,
                "ctr": 0.24,
                "ecpm": 51.04,
                "ecpc": 0.21,
                "fill_rate": 0.88,
                "impression_rate": 0.71
            },
            {
                "date": "2026-02-04",
                "request": 229331,
                "fill": 104599,
                "impression": 41741,
                "click": 20808,
                "revenue": 41937.05,
                "ctr": 0.5,
                "ecpm": 1004.7,
                "ecpc": 2.02,
                "fill_rate": 0.46,
                "impression_rate": 0.4
            },
            {
                "date": "2026-02-03",
                "request": 274371,
                "fill": 125010,
                "impression": 49950,
                "click": 25112,
                "revenue": 49847.48,
                "ctr": 0.5,
                "ecpm": 997.95,
                "ecpc": 1.99,
                "fill_rate": 0.46,
                "impression_rate": 0.4
            },
            {
                "date": "2026-02-02",
                "request": 45828,
                "fill": 21103,
                "impression": 8661,
                "click": 4190,
                "revenue": 8392.84,
                "ctr": 0.48,
                "ecpm": 969.04,
                "ecpc": 2,
                "fill_rate": 0.46,
                "impression_rate": 0.41
            }
        ],
        "summary": {
            "request": 550111,
            "fill": 251286,
            "impression": 100742,
            "click": 50160,
            "revenue": 100183.56,
            "fill_rate": 0.46,
            "impression_rate": 0.4,
            "ctr": 0.5,
            "ecpm": 994.46,
            "ecpc": 2
        },
        "page": {
            "current": 1,
            "page_size": 10,
            "total": 5
        }
    }
}

---

7. Request Example (curl)

curl --location --request POST 'https://developer.gocarty.net/api/report/out-search' \
--header 'Authorization: rk_mxuyl6eq6lcz3mlkhz89gqcjinmj5qvx' \
--header 'Content-Type: application/json' \
--data-raw '{
  "start_date": "2026-02-01",
  "end_date": "2026-02-07",
  "group": [
    "date"
  ],
  "page": 1,
  "page_size": 10
}'

---

8. Error Code Description (Example)

Code	Description
0	success
Non-zero	Parameter error / Authentication failure / System error

Common Error Scenarios

• Missing or invalid Authorization header
• Invalid date format or date range
• Invalid page or page_size parameters

---