api/v1/report
Use the ap1/v1/report endpoint to request measurement report data (the DT Growth report). You can request a maximum of 100 reports per day and 5 reports per minute.
Host URL
https://reporting.digitalturbine.com
Method
POST
Endpoint
/api/v1/report
Headers
Content-Type: application/json
Authorization: Bearer
JSON Request Body for Filtered Data
The following sample body of a JSON request is for a DT Growth report for installs, impressions, clicks, and ad spend for the week of September 15, 2023 through September 22, 2023. The .csv file contains data only for USA, Canada, and Russia and will be grouped by date and country.
{
"product": "dtgrowth",
"query": {
"dateRange": {
"start": "2023-09-15",
"end": "2023-09-22"
},
"metrics": [
"Installs",
"Impressions",
"Clicks",
"Spend"
],
"splits": [
"Date",
"Country"
],
"filters": [
{
"dimension": "Country",
"values": [
"US",
"CA",
"RU"
]
}
],
"reportFormat": "csv"
}
}product
String
Required
Must specify dtgrowth.
query
array
Required
Data you want to include in the report
query.dateRang
array
Required
The time span that the report should cover. The maximum date range is 90 days. Invalid dates result in an empty report.
query.dateRange.start
String
Required
Start of the date range for the report. The generated report includes metrics for the specified start date. The start date must meet the following requirements:
- The start date must be earlier or equal to the end date.
- Specify the start date in YYYY-MM-DD format.
query.dateRange.end
String
Required
End of the date range for the report. The generated report includes metrics for the specified end date. The end date must meet the following requirements:
- The end date cannot be a future date.
- Specify the end date in YYYY-MM-DD format.
query.metrics
array
Required
The type of data (metric) you want to include in the report. You must specify at least 1 metric. For a complete list of supported metrics, see DT Growth Reporting Metrics.
query.splits
array
Required
Dimensions by which you want to group data into sections. For a complete list of supported dimensions, see DT Growth Reporting Dimensions. If you do not want to group report data, send an empty array.
query.filters
array
Required
The Reporting API supports various dimensions by which you can filter report data. You can query any of the 7 supported dimensions in a single query. However, for each dimension, you can only specify up to 5 values. If you do not want to apply any filters, send an empty array.
query.reportFormat
string
Required
File type for the generated report. The only supported file type is .csv. You must specify csv.
JSON Body for Unfiltered data
The following sample body of a JSON request is for a DT Growth report for only impressions for the week of September 15, 2023 through September 22, 2023. The .csv file contains data that is unfiltered.
Report Request Responses
The following code samples show both successful and unsuccessful report request responses.
Successful Report Request Response
status
boolean
Status of the
id
string
Unique identifier for the generated report. This ID may be used to troubleshoot reporting errors.
signed_url
string
URL that you must poll until the report is populated. This URL is valid for three hours.
Unsuccessful Report Request Response
Report Request Error Codes
The table below shows the main errors indicating an unsuccessful response.
405 Method_Not_Allowed
Request method was not supported. For report requests, use the POST method
401 Unauthorized
invalid_token
Authorization token error due to the following scenarios: - Missing or invalid Authorization header - Missing or invalid Token in Authorization header - Token could not be verified - Failed to resolve group_id (subject) from token
401 Unauthorized
token_expired
The access token is older than 1 hour old and no longer valid. Obtain a new access token, and re-send the report request using the new token. For more information about obtaining an authorization token, see Obtain an access token.
400 Bad_Request
invalid_request
Empty or invalid Content-Type in the request header. Ensure that you are sending Report Requests in JSON format.
400 Bad_Request
invalid_product
Empty or invalid product specification. You must specify dtgrowth.
400 Bad_Request
invalid_query
Invalid values specified for report parameters. Check that format of all parameter specifications are correct. For more information about Report Request parameters, see JSON Request Body for Filtered Data.
500 Internal_Server_Error
internal_server_error
Reporting API server connection error
504 Gateway_Timeout
product_timeout
Connection to the Reporting API server timed out while receiving the request.
500 Internal_Server_Error
internal_server_error
Error encountered while trying to fulfill the report request.
Last updated

