Query data

  • Published on Dec 12, 2025
Prev Next
Get
/query/data/json

Execute a query to retrieve data from a specified data source

Security
HTTP
Type bearer

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

Query parameters
json
Required

JSON-encoded data query parameters

object
api_key
string

API key when not using an authorization header

Max length255
Pattern^[A-Za-z0-9_-]+$
Exampleabc123def456
schedule_id
string

Schedule ID for this query request. If not provided, one will be generated from other query parameters

Max length50
Pattern^[A-Za-z0-9_-]+$
Examplemy_query_123
ds_id
string Required

Target data source ID

Max length50
Pattern^[A-Za-z0-9_-]+$
ExampleGAWA
ds_accounts

List of data source accounts the query should target, or a filter for them

Example[ "account123", "account456" ]
OneOf
string
string
Max length50
Pattern^[A-Za-z0-9_-]+$
array
array
string
Max length50
Pattern^[A-Za-z0-9_-]+$
object
object
ds_segments

List of data source segment IDs the query should target

Example[ "segment1", "segment2" ]
OneOf
string
string
Max length50
Pattern^[A-Za-z0-9_-]+$
array
array
string
Max length50
Pattern^[A-Za-z0-9_-]+$
ds_user
string

Shorthand parameter to provide one value for ds_users

Max length255
Exampleuser@example.com
ds_users

List of data source login usernames to limit when searching for suitable authentication

OneOf
string
string
Max length255
array
array
string
Max length255
date_range_type
string

Type of date range the query should use

Max length50
start_date
string

Fixed or relative start date for your query

Max length100
Exampleyesterday
end_date
string

Fixed or relative end date for your query

Max length100
Exampleyesterday
compare_type
string

Date range comparison type. Defaults to none

Max length50
compare_show
string

When compare_type is custom, display type for comparison values

Max length50
compare_start_date
string

When compare_type is custom, fixed or relative start date for comparison

Max length100
compare_end_date
string

When compare_type is custom, fixed or relative end date for comparison

Max length100
fields

Target data source fields the query should return

OneOf
string
string
Max length1000
array
array
string
Max length100
array
array
object
settings
object

Settings that should be applied when performing the query

filter
string

Filter string that should be applied to the results

Max length5000
order_columns
string

Order instruction for fields that are split by column

Max length1000
order_rows

List of order fields and sort directions for result rows

OneOf
string
string
Max length1000
array
array
string
Max length100
max_columns
integer (int32)

Maximum number of columns the query results should contain

Minimum1
Maximum1000
max_rows
integer (int32)

Maximum number of rows the query results should contain

Minimum1
Maximum1000000
offset_start
integer (int32)

Starting row index for paginated response

Minimum0
Maximum1000000
offset_end
integer (int32)

Ending row index for paginated response

Minimum0
Maximum1000000
cache_minutes
integer (int32)

Maximum allowed age of query results cache in minutes

Minimum0
Maximum10080
sync_timeout
integer (int32)

Number of seconds the API should wait for query to finish

Minimum0
Maximum3600
Example{ "ds_id": "GAWA", "start_date": "yesterday", "end_date": "yesterday", "fields": [ "date", "sessions" ] }
Responses
200

Query executed successfully

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*
Expand All
object
meta
object
request_id
string

API request ID

Max length50
Pattern^[A-Za-z0-9_-]+$
schedule_id
string

Custom or generated schedule ID for the query

Max length50
Pattern^[A-Za-z0-9_-]+$
status_code
string

Status code for the query

Max length20
query
object
start_date
string

Query start date in YYYY-MM-DD format

Max length10
Pattern^\d{4}-\d{2}-\d{2}$
end_date
string

Query end date in YYYY-MM-DD format

Max length10
Pattern^\d{4}-\d{2}-\d{2}$
ds_accounts
Array of string

Data source account IDs used in the query

Max items100
string
Max length50
Pattern^[A-Za-z0-9_-]+$
ds_segments
Array of string

Data source segment IDs used in the query

Max items1000
string
Max length50
Pattern^[A-Za-z0-9_-]+$
fields
Array of object
Max items100
object
id
string

Field ID from the request

Max length100
Pattern^[A-Za-z0-9_-]+$
field_id
string

Field ID the API uses

Max length100
Pattern^[A-Za-z0-9_-]+$
field_name
string

Field name

Max length255
field_type
string

Field type

Max length10
field_split
string

Field split by type

Max length50
data_type
string

Field data type

Max length50
data_column
integer (int32)

Field value position in each data row

Minimum0
Maximum1000
visible
boolean

Whether data for this field is visible

compare_type
string

Date range comparison type used

Max length50
compare_show
string

Display type for comparison values

Max length50
compare_start_date
string

Start date for comparison date range

Max length10
Pattern^\d{4}-\d{2}-\d{2}$
compare_end_date
string

End date for comparison date range

Max length10
Pattern^\d{4}-\d{2}-\d{2}$
settings
object

Settings used in query

cache_minutes
integer (int32)

Requested maximum age of cache in minutes

Minimum0
Maximum10080
result
object
total_columns
integer (int32)

Total amount of columns

Minimum0
Maximum1000
total_rows
integer (int64)

Total amount of rows in data

Minimum0
Maximum100000000
run_seconds
number (float)

Number of seconds it took for the query to run

Minimum0
Maximum7200
data_sampled
boolean

If data source has provided sampled data

cache_used
boolean

If cached data was used

cache_time
string (date-time)

ISO 8601 datetime for the most recent cached data

Max length30
paginate
object
prev
string (uri)

URL to previous offset

Max length500
next
string (uri)

URL to next offset

Max length500
data
Array of array

Query result rows

Max items1000000
Array of string
Max items1000
string
Max length10000
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
403

Access forbidden

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
422

Unprocessable Entity - validation failed

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
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
429

Too Many Requests

Headers
X-RateLimit-Limit
integer
Request limit per hour
Minimum1
Maximum10000
Example5000
X-RateLimit-Remaining
integer
Remaining requests in current window
Minimum0
Maximum10000
Example4999
Retry-After
integer
Seconds until rate limit resets
Minimum1
Maximum86400
Example3600
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
500

Internal server error

Headers
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