Reporting API

Note

The data shared through our reporting tools should only be used for the purpose of performance analysis. Accurate billing numbers will be shared at the end of each month.

Reporting API Metrics and Dimensions

DT Growth Reporting API enables you to access performance data for the UA campaigns running across Digital Turbine formats. To access this data, the advertiser must set up a DT Growth campaign. 

Please look at the tab above for supported metrics and dimensions.

Reporting API Workflow

To pull data via the Growth Reporting API, you must: 

  1. Obtain the Access Token.
  2. Generate a reporting API request.
  3. Download the custom report. 

Step 1: Obtaining the Access Token

  1. Contact your Digital Turbine representative to get the Client ID and Client Secret.
    Digital Turbine sends the Client ID and Client Secret via encrypted email.
  2. Click the link to create or login to your Proofpoint Encryption account.
    Once logged in, you can view the email with the Client ID and Client Secret to be used below.

    Note

    If you click the email link and land on a page with an error, try downloading the file from the email and opening it, which should trigger the login.
    Please get in touch with your Digital Turbine representative if you have trouble accessing the email.

  3. Make a POST request - The base endpoint for the entire process is  https://reporting.digitialturbine.com 
Authentication Token
POST /auth/v1/token
Headers
Content-Type    application/json
Sample Request
 https://reporting.digitalturbine.com/auth/v1/token
Body: raw (application/json)
 {
"grant_type": "client_credentials",
"client_id": "3ce66d885XXXXXXXXXXa3b752bb9000",
"client_secret":"YtMvC7VYTQMQ7w9UCUaFXXXJnwVZnQqq00000yt8IIh2h8XFDuXXXXXXXXSS6XTrFWW4TkebCcMLJkrXSw5IurkearTJIDzUxsbiMXv8hb4T23MwN6eE7DDIthRFqDnhnuhiDlY2oPeaOjsMbzE8joZ5cs6tsySJz6uZXwJ-x3lcYaYbgXXXXXXXX3_hFeuXm-C7-me2V1MMs-ftJxTd5QbHoUhG3Q5anCWCW_pg8x3CL4yPGCbpWUDZfpdNPyyCT4rxCEb-VC0Bdqwe8N2GGn_VSFOwQYxa-yap2JuNSGJfl_ZURXXXXXXXXFe1GpHDn8pk7yYwQYIGAg"
       }
  • Grant Type must be "client_credentials"
  • The credentials are sent according to the OAuth 2.0 protocol

Sample Authentication Response

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

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

accessToken: The token required to continue the process
tokenType: Bearer
expiresIn: 3600 seconds (1 hour)

When a request is unsuccessful, you receive the following response:

Unsuccessful Response
{
        "error": "internal_server_error"
      }

Possible Authentication Errors

Set out in the table is a list of possible errors that resulted in an unsuccessful response.

HTTP Status Code Error Scenario
405 (Method_Not_Allowed N/A The request method is not POST
400 (Bad_Request) 400 (Bad_Request)

Empty content or wrong Content-Type in the request

400 (Bad_Request)
invalid_request Parsing error of content JSON
400 (Bad_Request) invalid_request Missing grant_type in the request
400 (Bad_Request) unsupported_grant_type Unsupported grant_type in request
400 (Bad_Request) invalid_request Missing or invalid client_id in the request
400 (Bad_Request) invalid_request Missing or invalid client_secret in the request
400 (Bad_Request) Invalid_client The requested user credentials were not found:
When the credentials are incorrect or cannot be recognized
When your account has been disabled
When the credentials have been revoked
400 (Bad_Request) invalid_client

The requested client_secret is not matched with the internal client_secret.

When the credentials are incorrect or cannot be recognized.

It can also occur when your account has been disabled or when the credentials have been revoked

Step 2: Generating a reporting API request

Use the access token you received in Step 1 to request your custom report.

Set out below is a request example with the following section settings:

  • Product
  • Query
  • Metrics
  • Splits
  • Filters
  • Report Format

Request Example

Set out below is a request example with the following section settings:

Product
  • dtgrowth - Product must be written in lowercase.
Query
  • Date Range
    Start date: 2023-09-15
    End date: 2023-09-22
  • Metrics
    Installs
    Impressions
    Clicks
    Spend
  • Splits (Dimensions)
    Date
    Country
  • Filters
    Dimension filtered: country
    Values filtered: US, CA and RU
  • Report Format
    csv
URL
https://reporting.digitalturbine.com/api/v1/report
Reports 
POST /api/v1/report
Headers
Content-Type:  application/json
Authorization: Bearer 
Body. raw (application/json)
{
  "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"
  }
}
If no filters are required, their value should be an empty array.
However, product and query (dateRange, metrics, splits, and reportFormat) must include a value.
For example: JSON
{
  "product": "dtgrowth",
  "query": {
    "dateRange": {
      "start": "2023-09-15",
      "end": "2023-09-22"
    },
    "metrics": [
      "Impressions"
    ],
    "splits": [
      "Date"
    ],
    "filters": [],
    "reportFormat": "csv"
  }
}

Responses

Below are examples of both successful and unsuccessful responses.
Response: Successful 
    {
"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…",
     }
  • The "id" field holds an identifier of the request for later troubleshooting if required.
  • The "url" field holds the URL to be polled (GET request) until the body response (file) is populated.
Response: Unsuccessful
{
        "error": "invalid_token"
      }

 Possible Errors

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

HTTP Status Code Error Description Scenario
405 (Method_Not_Allowed)  N/A N/A Request method is not POST
401 (Unauthorized) invalid_token N/A Missing Authorization header
401 (Unauthorized) invalid_token N/A Invalid Authorization heade
401 (Unauthorized) invalid_token N/A Missing Token in Authorization header
401 (Unauthorized) token_expired N/A Token expired
401 (Unauthorized) invalid_token N/A Token verification error
401 (Unauthorized) invalid_token N/A Failed to resolve group_id (subject) from token
400 (Bad_Request) invalid_request N/A Empty content or wrong Content-Type in the request
400 (Bad_Request) invalid_product Invalid product Unsupported product in request
400 (Bad_Request) invalid_query

For example:

Invalid value supplied to:

Query/date-range: start/end: Date

-or-

Invalid metrics: A, B, C

-or-

Invalid dimensions: A, B, C

-or-

Invalid filters supplied to:

query/filters/dimension: string

query/filters/values: array

-or-

Invalid report format: csv/object

If the query sent is not in the expected schema


The date range is not sent in the ISO 8601 format - an incorrect date format will result in an empty report


Invalid metrics




Invalid splits

Invalid filters


Invalid reportFormat

500 Internal_Server_Error internal_server_error N/A

Connection error

504 Gateway_Timeout product_timeout N/A

Connection timeout

500 Internal_Server_Error internal_server_error N/A

Product request error

500 Internal_Server_Error internal_server_error N/A

Other reporting error

Step 3: Receiving the Custom Report

To obtain the Custom Report, follow the steps below:

  1. Receive the URL from the successful response in Step 2
  2. Perform polling on the URL to access the file containing the custom report.
    The empty file is populated within one hour, depending on the query size
  3. Resend the request if the file is not populated with data after one hour. 

The URL is valid for three hours

Additional Information and Restrictions

It is essential to take note of the information, restrictions, and rules to ensure the reports provided to ensure a successful response.

General

  • All reports are presented in US dollars (USD).
  • The time zone used is UTC.
  • The DT Growth Reporting API is available daily, with a delay of up to 12 hours from the end of day UTC.  
    • We recommend waiting 12 hours after the end of the day UTC before pulling data for the previous day.
    • If pulling data before the 12 hours after the end of the day UTC, we recommend pulling the data again after the 12 hours to ensure a complete data capture.

Query Restrictions

  • All fields are mandatory. Splits and Filters can have an empty array
    See the example in Step 2
  • The time range for a report query is limited to 90 days.
  • Queries are limited to a maximum of 50 per day, per API
  • You can query each one of the defined dimensions in the Reporting API calls by up to 7 dimensions in a single query
  • You are restricted to 5 filters per query
  • To receive a breakdown by date, it must exist in the "splits" array

Date Range Restrictions

There are several rules that must be observed concerning the date range:

  • The start date and end date must be in the format of ISO 8601
    For example, 2019-10-03
  • The start date must be earlier or equal to the end date
  • The end date cannot be a future date
  • The start date and end date are included in the report

Any invalid date will result in an empty report.

Back to Top ⇧