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/api/v1/report
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.dateRange 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 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.

 

Back to Top ⇧