# 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.
```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"
}
}
```
| 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](https://docs.digitalturbine.com/dt-growth/reporting-api-metrics-and-dimensions#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.
```json
{
"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
```json
{
"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
```json
{
"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](https://docs.digitalturbine.com/dt-growth/using-the-reporting-api#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](#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. |