Reporting API

The DT Growth Reporting API enables you to access performance and event data for active user acquisition (UA) campaigns running across all Digital Turbine formats. Before you can access report data, you must set up and activate a DT Growth campaign.

The DT Growth Reporting API is available daily, with a delay of up to 12 hours from the end of day UTC. Due to this delay, DT recommends waiting 12 hours after the end of the day UTC before generating a report for the previous day. If you request a report before this time, DT recommends requesting another report after the 12-hour window in order to ensure a complete data capture for the previous day.

Notes

  • You are limited to a maximum of 50 report requests per day.
  • Data from the Reporting API is for performance analysis only. At the end of each month, DT shares comprehensive data that you can use for billing purposes.
Reporting API Metrics and Dimensions

Reporting API Workflow

To pull data via the Growth Reporting API, complete the following steps:

  1. Obtain an access token.
  2. Generate a Reporting API request.
  3. Download the custom report.

Obtain an Access Token

All requests for performance data via the Reporting API require an access token. To obtain an access token, you must first request credentials from your DT Representative and then pass those credentials using the POST method and /auth/v1/token endpoint. The Reporting API responds with your access token that is valid for 1 hour. 

To obtain an access token:

  1. Request Reporting API access credentials (Client ID and Client Secret) from your DT Representative. Your DT Representative sends your credentials according to OAuth 2.0 protocol in an encrypted email via Proofpoint. Proofpoint then notifies you via email that you have an encrypted email.
  2. In the notification email from Proofpoint, either click the link to create a Proofpoint Encryption account, or, if you already have a Proofpoint account, click the link to log in to your account. If either the link lands on page with an error, download and open the attached file in notification email. Opening the file should trigger the login process.

    Once logged in, you can view the encrypted email that contains your Reporting API access credentials. If you have trouble accessing the encrypted email in Proofpoint, contact your DT Representative.

  3. Send a request using the POST method and /auth/v1/token endpoint. See the following reference for the access token endpoint.
Host URL https://reporting.digitialturbine.com
Method POST
Endpoint /auth/v1/token
Headers Content-Type: application/json

 

Sample Authentication Request

 https://reporting.digitalturbine.com/auth/v1/token

 

{
"grant_type": "client_credentials",
"client_id": "3ce66d885XXXXXXXXXXa3b752bb9000",
"client_secret":"YtMvC7VYTQMQ7w9UCUaFXXXJnwVZnQqq00000yt8IIh2h8XFDuXXXXXXXXSS6XTrFWW4TkebCcMLJkrXSw5IurkearTJIDzUxsbiMXv8hb4T23MwN6eE7DDIthRFqDnhnuhiDlY2oPeaOjsMbzE8joZ5cs6tsySJz6uZXwJ-x3lcYaYbgXXXXXXXX3_hFeuXm-C7-me2V1MMs-ftJxTd5QbHoUhG3Q5anCWCW_pg8x3CL4yPGCbpWUDZfpdNPyyCT4rxCEb-VC0Bdqwe8N2GGn_VSFOwQYxa-yap2JuNSGJfl_ZURXXXXXXXXFe1GpHDn8pk7yYwQYIGAg"
}

 

PARAMETER TYPE STATUS DESCRIPTION
grant_type string Required Type of credentials you are sending. When sending API Report credentials, specify client_credentials.
client_id string Required Your Reporting API ID that DT sends via encrypted email.
client_secret string Required Your Reporting API password that DT sends via encrypted email.

 

Sample Authentication Responses

The Reporting API responds to with both successful and unsuccessful authentication token requests.

Successful Response

When an authentication request is successful, you receive the following response in JSON format:

{
        "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE1NzAwMTY5MDAsImV4cCI6MTU3MDAyMDUwMCwiYXVkIjoic3BlZWRiYWxsIiwic3ViIjoiMjEwMjYzIn0.hDo1waTytSys_oRhFNUPqZPom26bL05rxgtSt3XYHqI",
        "tokenType": "bearer",
        "expiresIn": 3600
      } 

 

RESPONSE PARAMETER TYPE DESCRIPTION
accessToken string Access token required for Reporting API requests
tokenType string Type of token issued.
expiresIn number Time in seconds that the token is valid. All tokens expire one hour after successful token request.

 

Unsuccessful Response

When a token request is unsuccessful, the Reporting API returns the following response:

{
  "error": "internal_server_error"
}

 

The following table provides possible errors that result in an unsuccessful response.

HTTP STATUS CODE ERROR CAUSE
405 (Method_Not_Allowed) N/A The request method is not POST
400 (Bad_Request) 400 (Bad_Request) Empty request body or incorrect Content-Type header
400 (Bad_Request) invalid_request

This error occurs for the following reasons:

  • Error while parsing JSON request body
  • Missing grant_type parameter in the request
  • Missing or invalid client_id
  • Missing or invalid client_secret
400 (Bad_Request) unsupported_grant_type Invalid grant_type. Always specify client_credentials.
400 (Bad_Request) invalid_client

This error occurs for the following reasons:

  • The requested credentials were not found
  • The requested credentials are incorrect or cannot be recognized
  • Your account has been disabled
  • Your credentials have been revoked

 

Generate a Report Request

You must include an access token with any report request. For more information about how to obtain an access token, see Obtain an Access Token. Once you obtain the access token, use the POST method and /api/v1/report endpoint to request a custom report. You can use various supported metrics and dimensions to specify what types of data to include in the report. For a complete list of supported metrics and dimensions, see Reporting API Metrics and Dimensions.

All generated reports have the following features:

  • All monetary data is in US dollars (USD).
  • The time zone of the report is UTC.
Host URL https://reporting.digitalturbine.com/api/v1/report
Method POST
Endpoint /api/v1/report
Headers Content-Type: application/json
Authorization: Bearer

 

Sample 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 Reporting API Metrics and Dimensions.
query.splits array Required

Dimensions by which you want to group data into sections. For a complete list of supported dimensions, see 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.

 

Sample 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.

Example of 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=20230922T112031Z&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.

 

Example of 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. For more information about the request header, see Generate a Reporting API request.
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 Sample 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.

 

Download the Requested Report

To download the requested report, perform polling on the URL (signed_url) from the successful response to a report request. The URL is valid for three hours.

Initial polling of the URL may show no report data. The Reporting system may take up to one hour to populate the report according to the report request. The Reporting system adds all report data to the empty report at once. Therefore, if there is any data present in the report, your report is complete. If your report is still not populated with data after one hour, resend the report request.

Back to Top ⇧