api/v1/report

Use the ap1/v1/report endpoint to request DT Growth report data. 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"
  }
}

PARAMETER	TYPE	STATUS	DESCRIPTION
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.

{
  "product": "dtgrowth",
  "query": {
    "dateRange": {
      "start": "2023-09-15",
      "end": "2023-09-22"
    },
    "metrics": [
      "Impressions"
    ],
    "splits": [
      "Date"
    ],
    "filters": [],
    "reportFormat": "csv"
  }
}

Report Request Responses

The following code samples show both successful and unsuccessful report request responses.

Successful Report Request Response

{
"status": true,
"id": "6fad42cb-25db-4af0-8988-1e7d8e6d90bc",
"signed_url":   "https://storage.googleapis.com/gcs-growth-agp-backend-standard-useast1-prod/reportingapi/backend/reports/223000/2023/09/22/11/2023092211_dt-growth-rapi-backend-listener-8479dc7d57-lq69t_657ad617-e7cd-4a6c-b371-031a014c015a.csv?X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Credential=sa-gke-rapi-backend%40agp-growth-prod-d1.iam.gserviceaccount.com%2F20230922%2Fauto%2Fstorage%2Fgoog4_request&X-Goog-Date=20240422T112031Z&X-Goog-Expires=10800&X-Goog-SignedHeaders=host&X-Goog-Signature=95455…",
}

RESPONSE PARAMETER	TYPE	DESCRIPTION
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

{
        "error": "invalid_token"
}

Report Request Error Codes

The table below shows the main errors indicating an unsuccessful response.

HTTP ERROR CODE	Error	Description
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.