Overview
This article covers Equativ’s reporting API, allowing you to request, generate and retrieve reports.
Authentication
For information about how to authenticate, refer to the API authentication article.
Base URL and endpoints
The base URL for reporting API requests is:
https://supply-api.eqtv.io/
| Method | Endpoint | Description |
|---|
| GET | /report-async | Returns all reports available for the authenticated user. |
| POST | /report-async | Generates an asynchronous report, based on the specified configuration. |
| GET | /report-async/{id} | Returns a specific report by id. |
| DELETE | /report-async/{id} | Deletes a report – either a one-time or a scheduled report |
Available dimensions and metrics
Learn more about the available dimensions and metrics in these articles:
Do not use commas ( , ) or semicolons ( ; ) in field names to avoid errors in the csv report files. The default field separator of the API is semicolon; thus, field names with semicolons might be treated as two columns. To avoid such problems, the report API puts fields in quotation marks automatically to ensure proper processing. However, the usage of semicolons is still not recommended.
Creating a basic report
Step 1 - Configure report parameters
Before you create the report, you must configure its parameters.
The sample below shows a configuration for a simple report with these characteristics:
- report name: doc_sample_1_simple_report
- includes data for the time frame Nov. 09, 2023 to Nov. 10, 2023*
- dimensions: by Day
- metrics: Impressions and Clicks
- e-mail address example@example.com will be notified once the report is ready
- useCaseId: Adserving - the report contains data related to direct campaigns/insertions only; i. e. RTB (programmatic) data is not included
{
"reportName": "doc_sample_1_simple_report",
"startDate": "2023-11-09T00:00:00",
"endDate": "2023-11-10T00:00:00",
"dimensions":[
"Day"
],
"metrics":[
"Impressions",
"Clicks"
],
"useCaseId": "Adserving",
"onFinishEmails": ["example@example.com"]
}
Step 2 - Generate report
To generate the report configured in Step 1, make a POST request to the
/report-async endpoint, specifying the report configuration in the request body:
POST https://supply-api.eqtv.io/report-async
You should receive a Status 200 (Success) response with the report Id.
Sample
ca327b57-335a-4068-bb22-c4c31c70cbef
Step 3 - Request report
To request the report, make a
GET request to the
/report-async/{id} endpoint, attaching the report Id received in Step 2.
Sample
GET https://supply-api.eqtv.io/report-async/ca327b57-335a-4068-bb22-c4c31c70cbef
Step 4 - Retrieve report
The response to the requested report contains the download link (URL) to the final report in csv format.
Sample
{
"id": "ca327b57-335a-4068-bb22-c4c31c70cbef",
"name": "doc_sample_1_simple_report",
"creationDate": "2023-11-22T12:34:43.27672Z",
"killed": false,
"configuration": "{\"StartDate\":\"2023-11-09T00:00:00\",\"EndDate\":\"2023-11-10T00:00:00\",\"Fields\":[{\"Field\":\"Day\",\"OrderBy\":null,\"OutputName\":\"Day\",\"DateFormat\":null},{\"Field\":\"Impressions\",\"OrderBy\":null,\"OutputName\":\"Impressions\",\"DateFormat\":null},{\"Field\":\"Clicks\",\"OrderBy\":null,\"OutputName\":\"Clicks\",\"DateFormat\":null}],\"Filters\":[[{\"Field\":\"IsRtb\",\"Operator\":\"IN\",\"Values\":[0]}]],\"FileFormat\":\"CSV\",\"IanaTimezone\":\"Europe/Paris\",\"UseCase\":\"AdServing\",\"Parameters\":{\"ClientId\":\"54585\"}}",
"status": 1,
"taskId": "c4761849-d02d-4e4c-b9d6-6a9db4c86b5e",
"instanceId": "https://storage.googleapis.com/bkt-dwh-read-reporting-prod-eu-reporting_output/2023/11/22/result_147020cc-6113-4060-a8e9-c4cadc74293c.csv.gz?X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Credential=webapi%40fs-async-reporting-prod.iam.gserviceaccount.com%2F20231122%2Fauto%2Fstorage%2Fgoog4_request&X-Goog-Date=20231122T123457Z&X-Goog-Expires=172800&X-Goog-SignedHeaders=host&X-Goog-Signature=0184317f034f03608485b0588ec89b0ab3d5a9723e05d27bd0ebd96bbce0de6ab6dbf0161cc9c2bcc0a83982a94b3d3c4511978d0a1fc425d1772c6c876d058bd4e9986142f2a9e7e2da2d6188f9b231d71178972dd11179b8957164f0223fe71297e52e1acdb852525df0b11928e91f453b5b1e6278b8cae2b8e49e9ab977f16193e1feca82628cf9f785743c77195c4028889f3cf9ca7dade2bd0a1b18db0adf093325096900f4cb479e3ee59ec9909b259f0b83d5bf5d8f09609286f8f3be944a6f433e2aea7d8f987a42e6736fb22cfe1514057a8a4ab00977fe057c9e609f00420c62be7467ca07d9ee28a324bb89e44e10ef5a255507d0bf9369738d56",
"networkId": 73,
"userId": 54585,
"isScheduled": false,
"schedulingStartDate": "2023-11-22T12:34:24.674345Z",
"schedulingEndDate": "2023-11-22T12:34:24.674353Z",
"datasource": "GCP"
}
Likewise, an email is sent from report@smartadserver.com to the e-mail address specified in the
onFinishEmails field, containing the download link. The link is freely accessible without credentials, but valid for two days only.
Report status
The table below lists the statuses returned in the the
status field in the response to a requested report.
Report
status Id | Report status description |
|---|
| 0 | IN_PROGRESS |
| 1 | SUCCESS |
| 4 | CSV_AVAILABLE_REPORT_TOO_BIG_FOR_XLSX (Not considered as failed) |
| 9 | JOB_FAILED |
| 17 | DELETED |
| 18 | SCHEDULED |
Use cases
The reporting API differentiates
metrics and
dimensions through the
useCaseId field, which can take one of the following values:
- Adserving - returns data related to direct (non-programmatic) campaigns/insertions
- RTB - returns programmatic data
- Holistic - returns both direct campaign/insertion data and programmatic data
Some dimensions and metrics can be used in both use cases, while others are specific to either the
Adserving use case or
RTB use case.
Sample Adserving use case
{
"reportName": "doc_sample_2_adserving",
"startDate": "2023-11-09T00:00:00",
"endDate": "2023-11-10T00:00:00",
"dimensions":[
"Day"
],
"metrics":[
"Impressions",
"Clicks"
],
"useCaseId": "Adserving",
"onFinishEmails": ["example@example.com"]
}
Sample RTB use case
{
"reportName": "doc_sample_3_rtb",
"startDate": "2023-11-09T00:00:00",
"endDate": "2023-11-10T00:00:00",
"dimensions":[
"Day"
],
"metrics":[
"Impressions",
"Clicks"
],
"useCaseId": "RTB",
"onFinishEmails": ["example@example.com"]
}
Related resources
