Query Report Data

The reportData.query method provides a synchronous way to retrieve report data. Unlike the standard Reports service, which generates file-based reports (CSV or Excel), this method returns structured JSON data directly in the response. It eliminates the need to define, create, and save a Report resource beforehand, making it ideal for real-time data retrieval and exploration.

Overview

Work through this guide to get familiar with using this endpoint to query your Campaign Manager 360 reporting data.

Prepare the request

Construct a ReportDataQueryRequest specifying the dimensions, metrics, date range, filters, and sorting criteria.

{
  "body": {
    "dateRange": "LAST_7_DAYS",
    "dimensionNames": [
      "advertiser",
      "campaign"
    ],
    "metricNames": [
      "impressions",
      "clicks"
    ],
    "sortBys": [
      {
        "name": "clicks",
        "sortOrder": "DESCENDING"
      }
    ],
    "maxResults": 100
  }
}

dateRange

A DateRange object specifying the time period for the query. This can be a custom date range or a relative date range.

dimensionNames

A list of standard dimension names to group by.

metricNames

Required. A list of standard metric names to include.

dimensionFilters

A list of DimensionValue objects used to filter the report data. Use this to restrict query results to specific values of a dimension.

sortBys

Sorting configurations for dimensions or metrics. Each configuration includes the field name and a sort order.

maxResults

The maximum number of rows to return per page (Default: 100, Max: 1000).

Pagination

The maxResults field controls the number of results returned in a single response. For example, if you set maxResults to 10, the API will return at most 10 results. It's possible that the API will return fewer than 10 results if there are fewer than 10 results that match your request.

If additional results are available, the response includes a nextPageToken. To retrieve the next page of results, send the same request again with the pageToken field set to this token. Keep all the other request parameters the same.

Send the request

Send an HTTP POST request to the reportdata/query endpoint:

POST https://dfareporting.googleapis.com/dfareporting/v5/userprofiles/{profileId}/reportdata/query

Ensure your request is authenticated with standard OAuth 2.0 credentials and necessary scopes. See Authorize Requests for more information.

Successful response

A successful query returns an HTTP 200 OK response with a JSON payload containing columnHeaders, rows, and totalRow.

{
  "columnHeaders": [
    { "name": "advertiser", "type": "DIMENSION" },
    { "name": "campaign", "type": "DIMENSION" },
    { "name": "impressions", "type": "METRIC" },
    { "name": "clicks", "type": "METRIC" }
  ],
  "rows": [
    {
      "values": [ "Test Advertiser", "Summer Campaign", "148672", "420" ]
    },
    {
      "values": [ "Test Advertiser", "Fall Campaign", "2159", "2" ]
    }
  ],
  "totalRow": {
    "values": [ "", "", "150831", "422" ]
  },
  "nextPageToken": "1234567890"
}

columnHeaders

The name and types (DIMENSION or METRIC) of the fields returned.

rows

A list of ReportDataRow objects containing the query results. The string values in each row align by position with the columnHeaders.

totalRow

A single aggregate row representing the sum of all matching metrics. Dimension fields and metrics that cannot be summed (for example, Reach metrics like uniqueReachTotalReach) are empty ("") in this row.

nextPageToken

A token used in a subsequent request to retrieve the next page if additional rows exist.

Latency and timeouts

Because this is a synchronous endpoint, queries execute immediately and data is returned directly in the response (up to the maxResults pagination limit). Queries have a maximum execution time of 60 seconds. If a query exceeds this limit, the API terminates the operation and returns an HTTP 503 Service Unavailable error.

If you encounter this error, try narrowing the date range, narrowing the filters (such as filtering by specific advertisers or campaigns), or reducing the number of requested dimensions and metrics. Alternatively, run a Report using reports.run to generate a downloadable report file asynchronously.

Query limits and constraints

The reportdata.query endpoint enforces several limits to ensure reliable responses. Requests that violate these constraints are rejected with an HTTP 400 Bad Request response.

Date range limits

• For custom date ranges, the startDate must be within the data availability period for the requested report data type. For details, see Data availability.

Metric and dimension constraints

• At least one metric must be provided in metricNames.
• Metrics and dimensions in the metricNames and dimensionNames lists must be unique.
• Metrics and dimensions that are labeled as Download only cannot be used in these queries.

Quota limits

Requests to this endpoint consume the following quotas:

• User rate limit: 120 requests per minute per user (2 QPS)
• Daily limit per project: 10,000 requests per day per project

Requests that exceed these limits fail with an HTTP 429 Too Many Requests error. If you page through results, each request for a new page (using the pageToken parameter) counts as a separate query and consumes from this quota.