Reporting API

warning

We will stop supporting Reporting API v1.x on 01/01/2026. Please migrate to Reporting API v2 from now.

Request address

https://api.premiumads.net/v2/reports

Authorization Header

Header	Type	Value	Description
Authorization	String	Bearer ${access_token}	A publisher token to authenticate calls to a PremiumAds API. Send your generated access token in place of the placeholder, ${access_token}, to authenticate your requests.

Get your access token HERE

Request Parameter

Fields	Type	Description	Required	Default
from	String	The start time of the requested data, in the format YYYY-mm-dd.	Yes	7 days ago
to	String	End time of the requested data, in the format YYYY-mm-dd.	Yes	Today
dimensions	String	Enum field: "date", "app", "zone", "country". Separate with commas for multiple fields. Examples: "date,app,country"	No	date

warning

The maximum date range limit is 31 days

How to get report data:

• Send a request with reporting parameters to the API Endpoint to receive a response containing report_id. • Create a loop to request the API Endpoint with report_id (recommended: 1 minute for interval). Until the status is Success, the response will include a download link (download_url) for the report file (.gz). • Download the file from download_url, then extract the .gz file to get the report in .csv format. • Process the .csv file as needed for your own purpose.

> Step 1: Send Request and receive report_id

API Url:

https://api.premiumads.net/v2/reports?from=[YYYY-MM-DD]&to=[YYYY-MM-DD]

cURL Example:

curl -X GET "https://api.premiumads.net/v2/reports?from=2025-09-16&to=2025-09-17&dimensions=date,app" \
     -H "Authorization: Bearer "

Response Data Example:

{
    "report_id": "e7445b9bd9d34b52b5f7e723151963e46a3479506723198d44c8f7956726f4cd_39456c39f6951df5f647321c79c993c8",
    "meta": {
        "from": "2025-01-01",
        "to": "2025-01-03",
        "dimensions": [
            "date",
            "app",
            "zone",
            "country"
        ]
    },
    "status": "Pending",
    "message": "Report is pending and will be processed soon.",
    "request_at": "2025-08-28 07:47:46 (UTC)"
}

Error Response Example:

{
    "error": "Date range must be less than or equal to 30"
}

> Step 2: Polling Request with report_id until status is Success

API Url:

https://api.premiumads.net/v2/reports?report_id=[REPORT_ID]

cURL Example:

curl -X GET "https://api.premiumads.net/v2/reports?report_id=e7445b9bd9d34b52b5f7e723151963e46a3479506723198d44c8f7956726f4cd_39456c39f6951df5f647321c79c993c8" \
     -H "Authorization: Bearer "

Response Data Example:

{
    "report_id": "e7445b9bd9d34b52b5f7e723151963e46a3479506723198d44c8f7956726f4cd_39456c39f6951df5f647321c79c993c8",
    "meta": {
        "from": "2025-01-01",
        "to": "2025-01-03",
            "dimensions": [
            "date",
            "country"
        ]
    },
    "status": "Success",
    "message": "Report is ready and available for download.",
    "request_at": "2025-08-28 07:47:46 (UTC)",
    "success_at": "2025-08-28 07:49:12 (UTC)",
    "download_url": "https://d1.premiumads.net/reportsV2/2025-08-01/e7445b9bd9d34b52b5f7e723151963e46a3479506723198d44c8f7956726f4cd_39456c39f6951df5f647321c79c993c8.csv.gz",
    "file_size": "26278" // in KB
}

Error Response Example:

{
    "error": "Report ID not found"
}

danger

The download_url is valid for ** 24 hours ** from the time the report is successfully generated. After that, you will need to request a new report.