Batch queries

  • Updated on Sep 15, 2025
  • Published on Sep 14, 2025
Prev Next

Perform multiple data source queries using a single batch request.

Please note that this functionality is in Preview and might be changed without prior notice. Please let us know of any issues you might encounter to help us improve this solution.

Overview

Query batches are intended for situations when the number of queries is very high, and both requesting and polling each query individually become impractical.

Starting a query batch

Send one request containing multiple queries. They are processed in the order they appear in the list.

POST /enterprise/v2/query/batch
Authorization: Bearer <your api key>
Content-Type: application/json

{
    "queries": [
        {
            "ds_id": "AW",
            "ds_accounts": "123456789",
            "start_date": "2022-09-01",
            "end_date": "2022-09-03",
            "fields": "date,impressions,cost"
        },
        {
            "ds_id": "AW",
            "ds_accounts": "234567890",
            "start_date": "2022-09-01",
            "end_date": "2022-09-03",
            "fields": "date,clicks,views"
        }
    ]
}

You can use split_accounts_policy to duplicate the same query for each account ID mentioned in the query, to run them separately from each other.

Polling for status

Using the returned batch_id, you can then poll for the status of all the queries in the batch. They are returned in the same order they were created.

GET /enterprise/v2/query/batch/qrb_3feb5ff5c71e

Retrieving results

As queries finish, you can retrieve query results from the returned result URLs. Please remember to provide authentication credentials when accessing URLs.

"results_info": {
  "total_rows": 47,
  "results_url": "https://.../results?schedule_id=qrb_3feb5ff5c71e_query_1"
}

Handling errors

Any errors that might occur while running the query are reported for each query separately.

"error_info": {
  "status": 500,
  "code": "QUERY_ACCOUNT_UNAVAILABLE",
  "message": "Account is not available",
  "description": "Google Ads account \"123456789\" is no longer available."
}

Restrictions

Please contact us to raise limits or to address other restrictions.

Usage limits

  • Maximum allowed runtime for a batch run is 60 minutes.

  • Number of concurrently running batches is limited to two batches at-a-time. Any additional batch runs will be placed in a queue, and processed in the order they were received.

  • Number of individual queries in a single batch, after splitting is applied, is limited to maximum of 100 queries.

  • Each performed query is still affected by the same license limitations that would be used when running queries individually, such as query concurrency.

Splitting

  • Splitting queries by date range does not support date range types. You can however use both fixed and relative start and end dates.

  • Splitting queries by accounts does not support all accounts.

Data retention

  • Query batch information is available for 90 days from the moment the batch was created.

  • Query batch status is available up to one hour after the batch run has stopped.