Create batched query

  • Updated on Nov 24, 2025
  • Published on Nov 4, 2025
Prev Next
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
object
ds_id
string
ds_accounts
string
start_date
string (date)
end_date
string (date)
fields
string
settings
object
string
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*
object

RFC 9457 Problem Details for HTTP APIs

type
string (uri)

A URI reference that identifies the problem type

Max length255
Examplehttps://supermetrics.com/problems/unauthorized
title
string

A short, human-readable summary of the problem type

Max length255
Pattern^[A-Za-z0-9\s]+$
ExampleUnauthorized
status
integer (int32)

The HTTP status code

Minimum100
Maximum599
Example401
detail
string

A human-readable explanation specific to this occurrence

Max length1000
Pattern^[A-Za-z0-9\s.,\-]+$
ExampleAuthentication required
instance
string (uri)

A URI reference that identifies the specific occurrence

Max length255
Examplehttps://api.supermetrics.com/v2/api-keys
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*
object

RFC 9457 Problem Details for HTTP APIs

type
string (uri)

A URI reference that identifies the problem type

Max length255
Examplehttps://supermetrics.com/problems/unauthorized
title
string

A short, human-readable summary of the problem type

Max length255
Pattern^[A-Za-z0-9\s]+$
ExampleUnauthorized
status
integer (int32)

The HTTP status code

Minimum100
Maximum599
Example401
detail
string

A human-readable explanation specific to this occurrence

Max length1000
Pattern^[A-Za-z0-9\s.,\-]+$
ExampleAuthentication required
instance
string (uri)

A URI reference that identifies the specific occurrence

Max length255
Examplehttps://api.supermetrics.com/v2/api-keys