---
title: "Query a report; larger requests return an asynchronous extraction"
method: POST
path: "/v1/reports/query"
---

# Query a report; larger requests return an asynchronous extraction

`POST /v1/reports/query`

## Request

- Base URL: `https://api.getmcpads.com`
- URL: `https://api.getmcpads.com/v1/reports/query`
- Auth: HTTP bearer

## Request body

- ReportQuery
  - `source` string, required
  - `account_ids` string[], required
  - `date_range` object, required
    - `start` string, date, required
    - `end` string, date, required
  - `level` 'account' | 'campaign' | 'ad_group' | 'ad'
  - `dimensions` string[], required: Include date for daily rows; omit it for native totals over date_range, grouped by the selected dimensions. Filters apply to these report rows.
  - `metrics` string[], required
  - `openai_ads_options` object: ChatGPT Ads report attribution, retained on exports and every refresh. Campaign goals are unchanged. Add one country/device/platform dimension for delivery breakdowns.
    - `attribution_window_days` 7 | 14 | 30
    - `view_through_attribution_window_days` 0 | 1
    - `attribution_time_basis` 'ad_event_time' | 'conversion_time'
  - `adjust_options` object: Adjust only. Saved measurement settings are reused on every export and refresh; reporting environment comes from the selected connection.
    - `currency` string: Defaults to the application's native currency.
    - `utc_offset` string
    - `attribution_source` 'first' | 'dynamic'
    - `attribution_types` string[]
    - `reattributed` 'all' | 'true' | 'false'
    - `ad_spend_mode` 'adjust' | 'network' | 'mixed'
    - `cohort_maturity` 'mature' | 'immature'
    - `os_names` string[]
    - `iap_revenue_mode` 'GROSS_100' | 'GROSS_85' | 'GROSS_70' | 'GROSS_60'
  - `resource` string: Google Ads resource from the source catalog.
  - `report_type` string: Microsoft, Amazon, Apple or Pinterest report type from catalog.query_options.
  - `attribution_days` '1' | '7' | '14' | '30': Amazon attribution window.
  - `placement` 'ALL_ON_TWITTER' | 'PUBLISHER_NETWORK'
  - `entity_ids` string[]: Optional X entity IDs or Apple campaign parent IDs.
  - `filters` object[]
    - `field` string, required
    - `operator` 'eq' | 'in' | 'contains' | 'gt' | 'gte' | 'lt' | 'lte', required
    - `value` unknown, required

## Response `200`

Successful response

## Other responses

- `201`: Resource created
- `202`: Extraction accepted; poll the Location URL
- `401`: Invalid or expired credential
- `403`: Account or scope not allowed
- `404`: Resource not found
- `409`: Resource state or idempotency conflict
- `410`: Extraction expired
- `422`: Invalid report or incompatible fields
- `429`: Request or row allowance reached
- `503`: Temporary service failure

---

[API](https://skmtc.dev/getmcpads/apis/get-mcp-ads-data-api.md) · [All operations](https://skmtc.dev/getmcpads/apis/get-mcp-ads-data-api/llms.txt) · [OpenAPI document](https://skmtc.dev/getmcpads/apis/get-mcp-ads-data-api/revisions/49546e2c14f3?raw)