The [`reportData.query`](https://developers.google.com/doubleclick-advertisers/current/reportData/query) method provides a synchronous
way to retrieve report data. Unlike the standard [`Reports`](https://developers.google.com/doubleclick-advertisers/rest/v5/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`](https://developers.google.com/doubleclick-advertisers/current/reportData/query#reportdataqueryrequest)
specifying the dimensions, metrics, date range, filters, and sorting criteria.

### REST

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

`dateRange`
:   A [`DateRange`](https://developers.google.com/doubleclick-advertisers/current/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](https://developers.google.com/doubleclick-advertisers/current/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`](https://developers.google.com/doubleclick-advertisers/current/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](https://developers.google.com/doubleclick-advertisers/authorizing) 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`](https://developers.google.com/doubleclick-advertisers/current/reportData/query#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`](https://developers.google.com/doubleclick-advertisers/current/reports/run) to generate a downloadable report
file asynchronously.

## Query limits and constraints

The [`reportdata.query`](https://developers.google.com/doubleclick-advertisers/current/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](https://support.google.com/campaignmanager/answer/6110224).

### 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](https://support.google.com/campaignmanager/answer/15407720) 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.