Run a query on a dataset and return its rows

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_filter usually 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. limit can lower this but not raise it; a larger
    value is rejected. When more rows matched, truncated is true and warnings says 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 gets 429, 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.

Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…

Scope

data-datasets:read

Path Params
string
required

The dataset's dataset value exactly as returned by GET /data-search/datasets. Do not guess or construct this value.

Body Params
fields
array of strings
required
length between 1 and 100

The fields to return, using the exact name values from GET /data-search/datasets/{dataset}/details. 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.

fields*
filters
object

Filters to apply, as a map of field name to Looker filter expression, for example last 7 days or Support Queue. Only fields whose can_filter is true can be filtered. The dataset's always_filter entries are applied even if you omit them; sending a filter on the same field replaces the default value. Always include a filter on the dataset's date field for the period asked about, and keep it short (see the endpoint description). Account scoping is applied server-side and cannot be set here.

sorts
array of strings
length ≤ 20

Fields to sort by, in order of precedence. Append desc for descending order, for example contacts.talk_time desc. Only fields whose sortable is true can be used.

sorts
integer
1 to 1000
Defaults to 1000

Maximum number of rows to return. When omitted the server maximum applies. That maximum is an environment setting (1000 rows by default) and can differ, so it may be lower or higher than 1000. A value above it is rejected rather than lowered, and the error states the exact maximum, so a capped result can never be mistaken for the one you asked for.

Responses

429

Too 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.

Language
Credentials
OAuth2
URL
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json