Create batched query

Updated on Jun 23, 2026
Published on Dec 12, 2025

Post

/query/batch

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

Security

HTTP

Type bearer

Bearer token authentication. Include the token in the Authorization header: Authorization: Bearer <your-token>

Body parameters

Expand All

object

queries

Array Required

OneOf

object

ds_id

string

ds_accounts

string

start_date

string (date)

end_date

string (date)

fields

string

settings

object

string

description

string

split_accounts_policy

string

Valid values[ "all", "none" ]

Default"none"

split_dates_policy

string

Valid values[ "day", "none" ]

Default"none"

timeout_minutes

integer

Minimum5

Maximum60

Default30

query_concurrency

integer

Minimum1

Maximum50

Default5

query_output_format

string

Default"json"

add_exclude_account_errors

boolean

Defaultfalse

add_clean_data_types

boolean

Defaultfalse

Responses

201

Batch query created successfully

Expand All

object

meta

object

request_id

string

data

object (QueryBatch)

@type

string

Valid values[ "query_batch" ]

batch_id

string

status_code

string

Valid values[ "QUEUED", "RUNNING", "STOPPED" ]

schedule_time

string (date-time)

start_time

string (date-time)

end_time

string (date-time) | null

cancel_time

string (date-time) | null

description

string

split_accounts_policy

string

split_dates_policy

string

timeout_minutes

integer

query_amount

integer

query_concurrency

integer

query_output_format

string

add_exclude_account_errors

boolean

add_clean_data_types

boolean

links

object

status

object (ResourceUrl)

href

string

400

Bad request - invalid parameters

Headers

X-RateLimit-Limit

integer

Request limit per hour

Minimum1

Maximum10000

Example5000

X-RateLimit-Remaining

integer

Remaining requests in current window

Minimum0

Maximum10000

Example4999

Access-Control-Allow-Origin

string

CORS header

Valid values[ "*" ]

Max length255

Example*

{
  "meta": {
    "request_id": "BXaEFVtjc7TXaJxgZhmFgSUD9edqq_CN"
  },
  "error": {
    "code": "BAD_REQUEST",
    "message": "The request was invalid."
  }
}

Expand All

object

Standard envelope returned by all error (4xx/5xx) responses.

meta

object (CommonSchemas_Meta)

Metadata included in every API response.

request_id

string

Unique identifier for the request, for tracking and debugging.

Min length8

Max length64

Pattern^[A-Za-z0-9_-]+$

ExampleBXaEFVtjc7TXaJxgZhmFgSUD9edqq_CN

error

object (ErrorResponse_Error)

Machine- and human-readable detail for a failed request.

code

string

Stable, screaming-snake-case identifier for the error condition. Clients should branch on this, not on message. Common values include BAD_REQUEST, UNAUTHORIZED, FORBIDDEN, NOT_FOUND, CONFLICT_ERROR, PERMISSION_ERROR, UNPROCESSABLE_ENTITY, UNPROCESSABLE_CONTENT, TOO_MANY_REQUESTS, INTERNAL_SERVER_ERROR, DUPLICATION_FAILED, SERVICE_UNAVAILABLE; domains may define additional codes.

Max length100

Pattern^[A-Z][A-Z0-9_]*$

ExampleBAD_REQUEST

message

string

Short, human-readable summary of the error.

Max length255

Pattern^.+$

ExampleThe request was invalid.

description

string

Optional longer explanation specific to this occurrence.

Max length2048

ExampleThe field 'display_name' must not be empty.

401

Unauthorized

Headers

WWW-Authenticate

string

Bearer token required

Max length255

Pattern^Bearer.*

X-RateLimit-Limit

integer

Request limit per hour

Minimum1

Maximum10000

Example5000

X-RateLimit-Remaining

integer

Remaining requests in current window

Minimum0

Maximum10000

Example4999

Access-Control-Allow-Origin

string

CORS header

Valid values[ "*" ]

Max length255

Example*

{
  "meta": {
    "request_id": "BXaEFVtjc7TXaJxgZhmFgSUD9edqq_CN"
  },
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication is required."
  }
}

Expand All

object

Standard envelope returned by all error (4xx/5xx) responses.

Documentation Index

Create batched query