Runs a structured query — fields, filters, sorts and a row limit — against one reporting dataset and returns the matching rows. This is how a reporting question gets its numbers.
Call this last. The sequence is: GET /data-search/datasets to pick the dataset, GET /data-search/datasets/{dataset}/details to learn its fields, then this endpoint using only the exact dataset and field name values those responses returned. Names that did not come from them are rejected.
Every query is bounded, and the bounds are part of the contract:
-
Always set a date filter, and keep the period short. There is no maximum period and the API does
not check the date range up front; what stops an oversized query is a limit on the data it may read,
so a query over more than about a month will usually time out or be stopped. The dataset's
always_filterusually supplies a default period, often short (for example one day), so set the
date filter explicitly to the period the user asked for. For a longer period, do not try one long
query first: send one query per calendar month (about 12 for a year) and combine the results
yourself. Counts and sums can be added together; averages, distinct counts and percentiles cannot, so
use the counts or sums they are made of when the dataset has them, and otherwise report each month
separately. A query that reads too much data is stopped and returns an error that says how to shrink it. -
At most 1000 rows are returned by default.
limitcan lower this but not raise it; a larger
value is rejected. When more rows matched,truncatedis true andwarningssays so. A truncated result
is incomplete: do not sum it, rank it or describe it as the full answer. Narrow the query, or
aggregate with a measure so the answer fits in fewer rows. -
The query must finish within the gateway timeout and under a data-scan limit. Exceeding
either is reported as an error whose message lists how to make the query smaller. Retrying an
unchanged request will fail the same way. -
Queries are rate limited per user. Run at most 5 queries at the same time, for example the widgets
of a dashboard or the pieces of a long period split into shorter queries: start the next one when one
finishes. If a request gets429, wait a few seconds and send the same request again, unchanged.
The numbers quoted here (1000 rows, the data-scan limit) are defaults. They are environment settings and can differ from one environment to another. The row limit in force is stated in warnings on a cut-off result and in the error for an out-of-range limit, so rely on those rather than on the number in this text. The data-scan limit has no number: a query that exceeds it gets an error saying it read too much data.
Selecting only dimensions returns individual rows; adding a measure aggregates over the dimensions you selected, and a measure with no dimension returns a single total. Prefer aggregating over listing rows: it is cheaper and makes truncation unlikely.
Read applied_filters in the response, not your request, when telling the user what period and conditions the numbers cover — it includes the dataset's always_filter entries merged with yours. Date values in the rows are rendered in the user's own account timezone.
Account scoping is applied server-side from the caller's own identity and is not part of this contract: results only ever contain the caller's account, and nothing sent in the request can widen that.
Example: for "How many calls did we get last week, per queue?" with dataset contacts — request the queue dimension and the interaction-count measure, filter the dataset's date field to last 7 days, and sort by the count descending. Then answer from rows, naming the period from applied_filters.
Every field in the response is read-only data about the user's own account. This endpoint cannot modify anything.
| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||
429Too many queries were sent by this user in a short time, and the request was not run. The request itself was fine: wait a few seconds and send the same request again, unchanged, and keep at most 5 queries running at the same time. Do not reformulate the question. The API gateway answers with an empty body, so there is no error message to read.