> ## Documentation Index > Fetch the complete documentation index at: https://docsy3.mile.app/llms.txt > Use this file to discover all available pages before exploring further. # Run analytics query > Runs a batch of 1 to 12 query specs and returns a `columns` and `rows` table for each item. The server applies the caller's organization and hub scope. A malformed spec fails the whole request (422), while a cost limit or engine failure fails only that item inside a 200 response. Rate-limited to 60 requests per minute per user. See the [Dashboard overview](/api-reference/analytics/dashboard-overview) for time ranges, limits and item statuses. Aggregates need `view/dashboard` only; the source's own view permission (`viewPermission`, `view/task` for the Task family, `view/data` for a Data source) is needed for Sample rows (Get sample rows) and for choosing the source in the widget composer, never for a card's numbers, with one exception: a `user` item that groups (at least one dimension) or filters (at least one filter) also needs `view/user`. Without it only that item comes back `no_permission` with `error.code` `data_source_forbidden`; the other items still run. A plain count of users (no dimension, no filter) needs `view/dashboard` only. On the `user` source, Group by Hub (`hub`) returns only the caller's own hubs when the caller is limited to some hubs: a user who also belongs to a hub the caller cannot see adds no bucket for that hub. Visibility: organization, hub, and team. A caller in a team sees Task sources (Task (Common field) and Task - {Flow}) limited to tasks assigned to members of their teams (users without a team count as members) or with no assignee, as in the task list, unless the query names assignees itself with an `assignee` `eq` or `in` filter (an `exists` or `range` filter on `assignee` still applies the team limit); when no member is found, only the caller's own tasks and tasks with no assignee. The User source is limited to users of the caller's teams plus users without a team. Data sources are not limited by team. An owner and a caller without a team are not limited. Team and hub both apply. ## OpenAPI ````yaml /openapi/public/openapi-analytics.json post /analytics/query openapi: 3.0.0 info: title: API - Analytics version: 3.0.0 description: API Documentation - RESTful API for field operations management. servers: - url: https://apiweb.mile.app/api/v3 security: - bearerAuth: [] tags: - name: Dashboard description: >- Dashboard lets a user compose their own dashboard from any number of cards, start from a template, duplicate a dashboard, share it with roles, and save it back as an organization template. Each card owns its own widget row (a chart type plus a query spec), cloned from the widget catalogue (built-in widgets plus the organization's custom widgets), so renaming or editing a card never touches the catalogue or another dashboard. Dashboards are owned by their creator: roles they are shared with can view, duplicate and save as template, but only the owner can edit or delete. Every write reuses the dashboard permission family (view, add, edit and delete dashboard). The numbers behind each card come from one generic aggregation endpoint instead of one endpoint per chart: the client sends a batch of up to 12 declarative query specs, the server injects the caller's organization, hub and soft-delete scope from the session, runs each spec read-only, and returns a flat columns and rows table per item. The catalog endpoints describe the data sources, fields and limits a client may use. - name: Report description: >- A report is a saved table definition over tasks of one flow or records of one data type: which fields to show, which hubs to include, and the default filters. - name: Insight Report description: >- Insight reports are written summaries of your operations, generated from your task and data records: findings, a summary and suggested actions. You set the context once per flow, then generate reports on demand or on a schedule. paths: /analytics/query: post: tags: - Dashboard summary: Run analytics query description: >- Runs a batch of 1 to 12 query specs and returns a `columns` and `rows` table for each item. The server applies the caller's organization and hub scope. A malformed spec fails the whole request (422), while a cost limit or engine failure fails only that item inside a 200 response. Rate-limited to 60 requests per minute per user. See the [Dashboard overview](/api-reference/analytics/dashboard-overview) for time ranges, limits and item statuses. Aggregates need `view/dashboard` only; the source's own view permission (`viewPermission`, `view/task` for the Task family, `view/data` for a Data source) is needed for Sample rows (Get sample rows) and for choosing the source in the widget composer, never for a card's numbers, with one exception: a `user` item that groups (at least one dimension) or filters (at least one filter) also needs `view/user`. Without it only that item comes back `no_permission` with `error.code` `data_source_forbidden`; the other items still run. A plain count of users (no dimension, no filter) needs `view/dashboard` only. On the `user` source, Group by Hub (`hub`) returns only the caller's own hubs when the caller is limited to some hubs: a user who also belongs to a hub the caller cannot see adds no bucket for that hub. Visibility: organization, hub, and team. A caller in a team sees Task sources (Task (Common field) and Task - {Flow}) limited to tasks assigned to members of their teams (users without a team count as members) or with no assignee, as in the task list, unless the query names assignees itself with an `assignee` `eq` or `in` filter (an `exists` or `range` filter on `assignee` still applies the team limit); when no member is found, only the caller's own tasks and tasks with no assignee. The User source is limited to users of the caller's teams plus users without a team. Data sources are not limited by team. An owner and a caller without a team are not limited. Team and hub both apply. operationId: runAnalyticsQuery requestBody: content: application/json: schema: type: object required: - queries properties: queries: type: array minItems: 1 maxItems: 12 items: type: object required: - id - spec properties: id: type: string description: >- Any non-empty string, echoed verbatim (normally the card's `cardId`) widgetId: type: string description: Optional; echoed and logged only spec: type: object required: - dataSourceId - timeField - measures properties: specVersion: type: integer enum: - 1 default: 1 dataSourceId: type: string description: >- `task` (Task (all)), `user`, `task_detail` (organizations without Big Data only; always unavailable), `task:` (Task - {Flow}: one flow of the organization, Big Data only, `flowId` = 24 hex, e.g. `task:65f0a1b2c3d4e5f6a7b8c9d0`) or `data:` (Data - {name}: one internal data type of the organization, every plan, `dataTypeId` = 24 lowercase hex, e.g. `data:6ae211692fd5463064096512`). A bare 24-hex id is no longer accepted (`422 data_source_id_invalid`). A well-formed id that does not resolve for the caller's organization (a flow of another organization, a deleted or system flow, `task_detail` for a Big Data organization, a data type of another organization, a deleted or external data type) fails only its own item with `error.code` `data_source_unavailable`; a malformed id is `422 data_source_id_invalid` for the whole batch. timeField: type: string description: >- Required on every spec. Must be one of the source's `timeFieldCandidates` (task: createdTime, updatedTime, startTime, endTime, doneTime; user: createdTime, verifiedTime, updatedTime, lastLogin - recorded but not applied, the user source is timeless; Data: the data type's date fields, then createdTime, updatedTime - recorded but not applied, a Data source is timeless and counts every record whatever the dashboard range). timeRange: type: object description: >- Either `preset`, or both `from` and `to` as calendar dates `YYYY-MM-DD` (anything else, including `2026-02-30`, relative words and datetimes, is `422 time_range_invalid`), widened to whole days on the batch `utcOffset`. Maximum 31 days, inclusive. properties: preset: type: string enum: - today - yesterday - last_7d - last_30d from: type: string to: type: string measures: type: array minItems: 1 maxItems: 3 items: type: object required: - id - fn properties: id: type: string description: Stable id, unique within `measures` fn: type: string enum: - count - cardinality - avg - sum - min - max - avgDuration - avgAge - doneShare description: >- Time measures are averages only: no median or percentile, no min/max of a duration, no on-time count, and age counts only tasks in the dashboard range. Each time function reads its own population, independent of the other measures of the spec: `avgDuration` = the mean of (to - from) in minutes over tasks that have both dates (and status `DONE` for a pair that ends or starts at `doneTime`), computed exactly, not sampled; `avgAge` = the mean of (now - date) in minutes over `UNASSIGNED`/`ONGOING` tasks whose date is already past, counting only tasks inside the dashboard range (at most 31 days), so an older open task is not included; `doneShare` = `DONE` tasks divided by all tasks in the bucket, a ratio from 0 to 1. `min`/`max` on a date field return the earliest/latest date-time among tasks that have that date. An empty population returns `null`, never 0. Each function is offered only when the catalog lists it as `supported` (the `user` source offers none of the three; a Data source offers `avgDuration` as a From / To only, when it has at least two date fields, and never `avgAge` or `doneShare`). On a Data source `avg`/`sum`/`min`/`max` need a field the index stores as a number; a number kept as text is a text field and cannot be summed. field: type: string description: >- Required for every `fn` except `count` and `doneShare`. `cardinality` needs a distinct-countable field; `avg`/`sum` a metricable one; `min`/`max` a metricable field or a date field (`createdTime`, `updatedTime`, `startTime`, `endTime`, `doneTime`), in which case the value is a date-time. `avgDuration` takes a duration pair id from the catalog `durationPairs` instead of a field. Task suggests `createdToDone`, `endToDone`, `startToDone`, `createdToStart`, `startToEnd`; every other ordered pair of `createdTime`/`startTime`/`endTime`/`doneTime` is also accepted (`createdToEnd`, `startToCreated`, `doneToEnd`, ...). An unknown id is `422 duration_pair_unknown`. `avgAge` takes a field from the catalog `ageFields` (Task: `createdTime`, `endTime`); any other field is `422 age_field_unknown`. `doneShare` takes no field (`422 measure_field_not_allowed`). For `avgDuration` give either `field` (a pair id) or `from` + `to`, never both (`422 duration_pair_conflict`). missing: type: string enum: - skip - zero default: skip description: >- `zero` is refused on `avgDuration`, `avgAge` and `doneShare` (`422 time_measure_missing_zero`): an empty population is `null`. label: type: string description: Echoed only from: type: string description: >- `avgDuration` only, together with `to`, instead of `field`: the start date column of a free From / To duration. Must be one of the source's `durationEndpoints` (Task: `createdTime`, `startTime`, `endTime`, `doneTime`; Task - {Flow}: those plus the flow's confirmed date components; Data: the data type's date fields and `createdTime`, never `updatedTime`). Rules: `from` without `to` (or the reverse) is `422 measure_field_missing`; `from` equal to `to` is `422 duration_fields_same`; an end that is not in `durationEndpoints` is `422 duration_field_not_date`; `from`/`to` together with `field` is `422 duration_pair_conflict`; `from`/`to` on any other `fn` is `422 measure_field_not_allowed`. The value is the mean of (to - from) in minutes over the tasks that have both dates. There is no hidden status rule: unlike the suggested pairs that end at `doneTime`, a From / To does not add `DONE` by itself; add a `status` filter for that. A From / To is a plain duration and may be negative (To earlier than From on average). to: type: string description: >- `avgDuration` only, together with `from`: the end date column of a free From / To duration. Same rules as `from`. dimensions: type: array maxItems: 2 items: type: object required: - id - kind - field properties: id: type: string kind: type: string enum: - terms - dateHistogram - geoGrid - ageBucket - hourOfDay - dayOfWeek description: >- Explicit discriminator; never inferred from the field type. `ageBucket` groups by the age of an age field (catalog `ageFields`) into the buckets of a preset named in `buckets`, always returned in preset order with every bucket present. `hourOfDay` / `dayOfWeek` group by the hour (0-23) / weekday (1 = Monday ... 7 = Sunday) of a time field (one of `timeFieldCandidates`, otherwise `422 dimension_field_not_time`) on the batch `utcOffset`, and always return 24 / 7 rows; an hour or weekday with no task is a row with count 0 and other measures `null`. None of the three takes a `granularity` (`422 dimension_granularity_not_allowed`). With one of them in the spec only one date grouping is allowed (`dateHistogram`, `ageBucket`, `hourOfDay`, `dayOfWeek`; otherwise `422 date_dimension_conflict`). `cardinality` and `avg` cannot be added up across hours or weekdays and are refused under `hourOfDay`/`dayOfWeek` (`422 fold_measure_unsupported`). A kind the data source does not support is `422 dimension_kind_unsupported` (a Data source supports `terms`, `dateHistogram`, `hourOfDay` and `dayOfWeek`; `ageBucket` and `geoGrid` are unsupported). Hourly grouping (`hourOfDay`, or a `minute`/`hour` `dateHistogram`) follows the field type: on a `date` field (no time of day) it fails the card with `time_grouping_date_only` on any source; on a `dateTime` field of a Data source it needs a `range` filter on that same field with both bounds, at most 31 days, else the card fails with `time_grouping_needs_range`. field: type: string description: >- `ageBucket`: a field from the catalog `ageFields` (`422 age_field_unknown`). `hourOfDay`/`dayOfWeek`: a time field. limit: type: integer minimum: 1 maximum: 1000 description: >- Mandatory for `terms`; never defaulted. A high-cardinality field is capped at 50 and may only be the first dimension. granularity: type: string enum: - minute - hour - day - week - month - quarter - year description: >- `dateHistogram` only (required there). Refused on `ageBucket`, `hourOfDay` and `dayOfWeek`. `minute` and `hour` follow the field type: on a `date` field (no time of day, any source) the card fails with `time_grouping_date_only`; on a `dateTime` field of a Data source (`data:`, which counts all records) they need a `range` filter on that same field with a lower and an upper bound spanning at most 31 calendar days, else the card fails with `time_grouping_needs_range` (results[i].status `error`, `error.field` = the field); its buckets are counted over that span. `day` to `year` are always allowed. buckets: type: string enum: - age_default description: >- `ageBucket` only (on any other kind `422 dimension_buckets_not_allowed`); required there, an unknown or missing preset is `422 bucket_preset_unknown`. Names a preset from the catalog `bucketPresets`; the bounds are computed by the server from now, the client never sends them. `age_default` returns the keys `lt1d` (under 1 day), `1to3d` (1-3 days), `3to7d` (3-7 days), `gte7d` (7 days or more), in that order. timezone: type: string description: >- Accepted for stored specs and ignored: buckets are cut on the batch `utcOffset`, the same clock as the time range gapFill: type: string enum: - 'null' - none default: 'null' description: >- `null` keeps empty buckets as rows of nulls; `none` drops them precision: type: integer minimum: 0 maximum: 6 default: 3 description: >- `geoGrid` only: decimal places of the rounded cell centre label: type: string filters: type: array items: type: object required: - id - field - operator properties: id: type: string field: type: string operator: type: string enum: - eq - in - range - exists value: description: >- Scalar for `eq`, array for `in`, object with any of `gte`/`gt`/`lte`/`lt` for `range`, ignored for `exists`. Option values are case-sensitive (`DONE`, not `Done`). sort: type: array items: type: object properties: by: type: string description: >- A measure or dimension id of this spec. A `terms` dimension sorted by a time measure keeps its top `limit` values by task count, then orders those by the time value: it is not a global top N by duration. direction: type: string enum: - asc - desc default: desc limit: type: integer minimum: 1 maximum: 1000 description: >- Row limit on the flattened result. With `hourOfDay`/`dayOfWeek` it counts the folded rows (24 / 7 per group). joins: type: array items: type: object additionalProperties: true description: >- Reserved. Absent or `[]` only; a non-empty array is `422 anlyt-006`. timeRange: type: object description: >- Either `preset`, or both `from` and `to` as calendar dates `YYYY-MM-DD` (anything else, including `2026-02-30`, relative words and datetimes, is `422 time_range_invalid`), widened to whole days on the batch `utcOffset`. Maximum 31 days, inclusive. properties: preset: type: string enum: - today - yesterday - last_7d - last_30d from: type: string to: type: string hubIds: type: array items: type: string description: >- Narrow to these hubs: a list of 24-character hex hub ids (anything else is `422 hub_ids_invalid`), each one of the caller's hubs (otherwise `403 hub_not_allowed`). Omitted or `[]` = every hub the caller belongs to; a caller with no hub sees no rows. utcOffset: type: string pattern: ^[+-]\d{2}:\d{2}$ example: '+07:00' description: >- Optional. The UTC offset (`±HH:MM`) day boundaries, `dateHistogram` buckets and the `hourOfDay`/`dayOfWeek` buckets are cut on. Absent = the organization calendar (`Asia/Jakarta`, +07:00). Anything else is `422 utc_offset_invalid`. mode: type: string enum: - debug description: >- Request the compiled engine query (internal accounts only; ignored otherwise) specVersion: type: integer description: >- Accepted at batch level; the spec-level value is the one validated example: timeRange: preset: last_30d hubIds: - 6650c2a1f3b9e4001c7d2c30 utcOffset: '+07:00' queries: - id: crd_01J8ZQ4R5W6X7Y8Z9A0B1C2D3E widgetId: 66f9a1c2e4b0a7d3c1f20b01 spec: specVersion: 1 dataSourceId: task timeField: startTime measures: - id: m1 fn: count dimensions: - id: d1 kind: dateHistogram field: startTime granularity: day gapFill: 'null' filters: - id: f1 field: status operator: eq value: DONE - id: crd_01J8ZQ4R5W6X7Y8Z9A0B1C2D3F spec: specVersion: 1 dataSourceId: task timeField: startTime measures: - id: m1 fn: count dimensions: - id: d1 kind: terms field: flow limit: 10 filters: [] sort: - by: m1 direction: desc - id: crd_01J8ZQ4R5W6X7Y8Z9A0B1C2D3G spec: specVersion: 1 dataSourceId: task timeField: doneTime timeRange: from: '2026-08-01' to: '2026-09-15' measures: - id: m1 fn: avg field: travelDuration dimensions: [] filters: [] - id: crd_01J8ZQ4R5W6X7Y8Z9A0B1C2D3H#active spec: specVersion: 1 dataSourceId: task timeField: startTime measures: - id: m1 fn: cardinality field: assignee dimensions: [] filters: [] - id: crd_01J8ZQ4R5W6X7Y8Z9A0B1C2D3H#total spec: specVersion: 1 dataSourceId: user timeField: createdTime measures: - id: m1 fn: count dimensions: [] filters: [] - id: crd_01J8ZQ4R5W6X7Y8Z9A0B1C2D3J spec: specVersion: 1 dataSourceId: task timeField: doneTime measures: - id: count fn: count dimensions: - id: cell kind: geoGrid field: doneCoordinate precision: 3 filters: [] - id: crd_01J8ZQ4R5W6X7Y8Z9A0B1C2D3K spec: specVersion: 1 dataSourceId: task timeField: doneTime measures: - id: m1 fn: avgDuration field: createdToDone dimensions: [] filters: [] - id: crd_01J8ZQ4R5W6X7Y8Z9A0B1C2D3L spec: specVersion: 1 dataSourceId: task timeField: createdTime measures: - id: m1 fn: count dimensions: - id: d1 kind: ageBucket field: createdTime buckets: age_default filters: - id: f1 field: status operator: in value: - UNASSIGNED - ONGOING - id: crd_01J8ZQ4R5W6X7Y8Z9A0B1C2D3M spec: specVersion: 1 dataSourceId: task timeField: doneTime measures: - id: m1 fn: count dimensions: - id: d1 kind: hourOfDay field: doneTime filters: - id: f1 field: status operator: eq value: DONE - id: crd_01J8ZQ4R5W6X7Y8Z9A0B1C2D3N spec: specVersion: 1 dataSourceId: data:6ae211692fd5463064096512 timeField: createdTime measures: - id: m1 fn: count dimensions: - id: d1 kind: terms field: status limit: 10 - id: crd_01J8ZQ4R5W6X7Y8Z9A0B1C2D3P spec: specVersion: 1 dataSourceId: user timeField: createdTime measures: - id: m1 fn: count dimensions: - id: d1 kind: terms field: status limit: 10 filters: [] description: Batch of up to 12 queries required: true responses: '200': description: >- Success - one result per item, in request order. Individual items can still be `error`, `timeout`, `no_data` or `no_permission`. In the example, the hour-of-day item shows only its first 3 rows; the API returns all 24 (0-23, on `utcOffset` +07:00). The Data source card (`...D3N`) counts all records of the data type, whatever the time range, and its dimension column carries the field `title`. The last item is a Users card: it counts the organization's users by account status, whatever the time range; because it groups, the caller needs `view/user` as well, or the item is `no_permission` with `data_source_forbidden`. Status values are `active`, `pending`, `disable`, `reject`, `inactive` and `unverified`, returned as stored. content: application/json: schema: type: object properties: status: type: boolean example: true specVersion: type: integer example: 1 resolvedTimeRange: type: object properties: from: type: string format: date-time to: type: string format: date-time timezone: type: string preset: type: string description: '`null` for an absolute range' results: type: array items: type: object properties: id: type: string description: The request item's `id`, echoed verbatim status: type: string enum: - ok - no_data - error - timeout - no_permission widgetId: type: string description: Present only when the request item carried one columns: type: array items: type: object description: >- Every column is `{id, role, fn, type, field, unit}` (`fn` on measures only); a dimension column also carries `kind` and `title`. `type` is the platform type of the column's field - `dateTime`, `date`, `option`, `text`, `number`. A measure is `number`, except `min`/`max` on a date field, which is `dateTime` (the value is epoch milliseconds). An `hourOfDay`/`dayOfWeek` dimension is `number`, an `ageBucket` dimension `text`. (`type` is left out of the schema and example on this page only because the docs build rewrites keys named `type`; the API does return it.) properties: id: type: string role: type: string enum: - dimension - measure fn: type: string description: Measures only field: type: string description: >- The dimension or measure field; for `avgDuration` the duration pair id, `null` for a From / To measure, for `count`/`doneShare` `null` unit: type: string description: >- `minute` for `avgDuration` and `avgAge`, `ratio` (0 to 1) for `doneShare`; otherwise the field's unit, or `plain` for a count kind: type: string description: >- Dimensions only: the dimension `kind` of the request (`terms`, `dateHistogram`, `ageBucket`, `hourOfDay`, `dayOfWeek`), so an hour (9), a weekday (1) or an age key (`lt1d`) is not read as a date signed: type: boolean description: >- On `avgDuration`. `true` only when the pair is a signed deadline pair (`endToDone`, `startToDone`, or a From / To whose `from`/`to` equal one of them, i.e. Deadline -> Done, Scheduled start -> Done): the value may be negative, and negative means done before the due (end) or start time. A From / To column over any other two dates carries `signed: false`: a plain process duration (e.g. check-in -> check-out) that may still be negative when To was on average earlier than From. from: type: string description: 'From / To measures only: the `from` field' to: type: string description: 'From / To measures only: the `to` field' fromTitle: type: string description: >- From / To measures only: the field title when `from` is a flow component or a data type field (data, shown as is), `null` for a core field toTitle: type: string description: >- From / To measures only: as `fromTitle`, for `to` title: type: string description: >- Dimensions only, always present: the field title when the field is a flow component (`task:`) or a data type field (`data:`), shown as is (data, not an i18n key); `null` for a core field (including the Data system fields `createdTime`, `updatedTime`, `createdBy`, `updatedBy`), which the client titles itself. rows: type: array items: type: array items: type: object additionalProperties: true description: >- Positional arrays matching `columns`. A missing value is `null`, never 0. `avgDuration`/`avgAge` are minutes (decimal), `doneShare` a ratio from 0 to 1, a date `min`/`max` epoch milliseconds; a time measure with no task in its population is `null`. An `hourOfDay` key is 0-23, a `dayOfWeek` key 1-7 (1 = Monday), an `ageBucket` key one of the preset keys in preset order. meta: type: object properties: bucketCount: type: integer rowCount: type: integer truncated: type: boolean description: >- A `terms` bucket list or the root `limit` cut rows fanOut: type: boolean description: >- A dimension groups by an array field (`assignee`): bucket totals can exceed the document total partial: type: boolean description: >- Elasticsearch timed out and returned partial results tookMs: type: integer basis: type: object additionalProperties: type: integer description: >- Spec without dimensions only, and only when a measure is `avgDuration`, `avgAge` or a date `min`/`max`: measure id -> number of tasks the value is based on (the population of that measure) basisRows: type: object additionalProperties: type: array items: type: integer description: >- Grouped spec only, for the same measures as `basis`: measure id -> one task count per row, aligned with `rows` error: type: object properties: code: type: string message: type: string field: type: string description: '`field_unavailable` only: the logical field name' description: >- On `error` and `no_permission`; on `timeout` only `message`. Per-item codes include `bucket_estimate_exceeded`, `engine_error`, `data_source_not_licensed` (`no_permission`), `data_source_forbidden` (`no_permission`: a `user` item that groups or filters, for a role without `view/user`), `data_source_unavailable` (the source does not resolve for this organization: a flow of another organization, a deleted or system flow, `task_detail` for a Big Data organization, a deleted data type, or a listed source that is unavailable), `team_scope_unresolved` (Task sources only: the caller's team members could not be resolved, so the card fails closed; retryable), and on a Task - {Flow} or Data source `field_unavailable` (the card names a column that is gone: a deleted or retyped component or data type field, a data type field no record carries any more, or on Task (all) and Task - {Flow} a retired Task field `docId`, `organizationName`, `organizationEmail`, `hubCountry`, `hubLat`, `hubLng` or `year`; `error.field` names it; permanent until the card is edited) or `source_columns_unchecked` (the source's columns could not be checked right now; no `field`; retryable). Fields hidden for a role are not removed and never cause an error: the index decides which columns a source has. debug: type: object description: 'Only for `mode: "debug"` from an internal account' properties: engine: type: string indices: type: array items: type: string query: type: object additionalProperties: true appliedVisibility: type: array items: type: string estimatedBuckets: type: integer tookMs: type: integer valueLabels: type: object description: >- Users source only (`user`): names for the team and hub ids the result shows, `{field: {id: name}}`, read from the caller's organization (`teamId` from teams, `hub` from hubs). The value in `rows` stays the id; an id with no name (deleted, other organization) is absent and the client shows the id. Omitted for every other source and when no labelled id is shown. additionalProperties: type: object additionalProperties: type: string example: hub: 65c59fee72f0501bee017e22: Jakarta Hub teamId: 6aebf16ee34f1683bd01e7f2: Team North examples: response: value: status: true specVersion: 1 resolvedTimeRange: from: '2026-09-01T00:00:00+07:00' to: '2026-09-30T23:59:59+07:00' timezone: Asia/Jakarta preset: last_30d results: - id: crd_01J8ZQ4R5W6X7Y8Z9A0B1C2D3E status: ok widgetId: 66f9a1c2e4b0a7d3c1f20b01 columns: - id: d1 role: dimension field: startTime unit: null - id: m1 role: measure fn: count field: null unit: plain rows: - - '2026-09-01T00:00:00+07:00' - 212 - - '2026-09-02T00:00:00+07:00' - null - - '2026-09-03T00:00:00+07:00' - 198 meta: bucketCount: 30 rowCount: 30 truncated: false fanOut: false partial: false tookMs: 4 - id: crd_01J8ZQ4R5W6X7Y8Z9A0B1C2D3F status: ok columns: - id: d1 role: dimension field: flow unit: null - id: m1 role: measure fn: count field: null unit: plain rows: - - Delivery - 812 - - Pickup - 140 meta: bucketCount: 2 rowCount: 2 truncated: false fanOut: false partial: false tookMs: 3 - id: crd_01J8ZQ4R5W6X7Y8Z9A0B1C2D3G status: error error: code: time_range_exceeded message: >- This widget asked for a 46 day range, but the limit is 31 days. Narrow the range rather than expecting a trimmed result. - id: crd_01J8ZQ4R5W6X7Y8Z9A0B1C2D3H#active status: ok columns: - id: m1 role: measure fn: cardinality field: assignee unit: plain rows: - - 37 meta: bucketCount: 1 rowCount: 1 truncated: false fanOut: false partial: false tookMs: 2 - id: crd_01J8ZQ4R5W6X7Y8Z9A0B1C2D3H#total status: ok columns: - id: m1 role: measure fn: count field: null unit: plain rows: - - 52 meta: bucketCount: 1 rowCount: 1 truncated: false fanOut: false partial: false tookMs: 1 - id: crd_01J8ZQ4R5W6X7Y8Z9A0B1C2D3J status: ok columns: - id: lat role: dimension field: doneCoordinate unit: latitude - id: lng role: dimension field: doneCoordinate unit: longitude - id: count role: measure fn: count field: null unit: plain rows: - - -6.2 - 106.817 - 318 - - -6.914 - 107.609 - 201 meta: scanned: 519 scanCap: 10000 scanTruncated: false parsed: 519 skipped: 0 returned: 2 cellCap: 5000 cellTruncated: false precision: 3 - id: crd_01J8ZQ4R5W6X7Y8Z9A0B1C2D3K status: ok columns: - id: m1 role: measure fn: avgDuration field: createdToDone unit: minute rows: - - 1520.5 meta: bucketCount: 1 rowCount: 1 truncated: false fanOut: false partial: false tookMs: 5 basis: m1: 128 - id: crd_01J8ZQ4R5W6X7Y8Z9A0B1C2D3L status: ok columns: - id: d1 role: dimension field: createdTime unit: null kind: ageBucket - id: m1 role: measure fn: count field: null unit: plain rows: - - lt1d - 14 - - 1to3d - 22 - - 3to7d - 9 - - gte7d - 31 meta: bucketCount: 4 rowCount: 4 truncated: false fanOut: false partial: false tookMs: 3 - id: crd_01J8ZQ4R5W6X7Y8Z9A0B1C2D3M status: ok columns: - id: d1 role: dimension field: doneTime unit: null kind: hourOfDay - id: m1 role: measure fn: count field: null unit: plain rows: - - 0 - 0 - - 1 - 2 - - 2 - 0 meta: bucketCount: 24 rowCount: 24 truncated: false fanOut: false partial: false tookMs: 6 - id: crd_01J8ZQ4R5W6X7Y8Z9A0B1C2D3N status: ok columns: - id: d1 role: dimension field: status unit: null kind: terms title: Status - id: m1 role: measure fn: count field: null unit: plain rows: - - open - 12 - - closed - 7 - - hold - 2 meta: bucketCount: 3 rowCount: 3 truncated: false fanOut: false partial: false tookMs: 4 - id: crd_01J8ZQ4R5W6X7Y8Z9A0B1C2D3P status: ok columns: - id: d1 role: dimension field: status unit: null kind: terms title: null - id: m1 role: measure fn: count field: null unit: plain rows: - - active - 42 - - pending - 6 - - disable - 3 - - unverified - 1 meta: bucketCount: 4 rowCount: 4 truncated: false fanOut: false partial: false tookMs: 3 '401': description: >- Unauthorized - no valid token (`auth-034`), or an authenticated user with no organization content: application/json: schema: type: object properties: status: type: boolean example: false message: type: string description: Human-readable reason failedCode: type: string description: Structured error code, see Status Codes examples: response: value: status: false message: Unauthenticated. failedCode: auth-034 '403': description: >- Forbidden - `hub_not_allowed` when `hubIds` names a hub the caller does not belong to (no query runs). A role without `view/dashboard` gets `sys-035` instead. content: application/json: schema: type: object properties: status: type: boolean example: false message: type: string error: type: object properties: code: type: string description: >- Descriptive string code, e.g. `batch_too_large`, `field_unknown`, `hub_not_allowed` message: type: string field: type: string description: Offending key, when known examples: response: value: status: false message: >- You do not have access to hub(s): 6650c2a1f3b9e4001c7d2c31. error: code: hub_not_allowed message: >- You do not have access to hub(s): 6650c2a1f3b9e4001c7d2c31. '422': description: >- Unprocessable - the batch or one of its specs is malformed; nothing ran. `error.code` names the rule, e.g. `batch_too_large`, `queries_empty`, `unknown_key`, `time_range_missing`, `time_range_preset_unknown`, `field_unknown`, `field_blocked`, `protected_field_rejected`, `terms_limit_required`, `too_many_measures`, `option_value_unknown`, `anlyt-006` (non-empty `joins`). Time measures and dimensions: `duration_pair_unknown`, `age_field_unknown`, `bucket_preset_unknown`, `dimension_kind_unsupported`, `time_measure_missing_zero`, `measure_field_not_allowed`, `dimension_buckets_not_allowed`, `dimension_granularity_not_allowed`, `date_dimension_conflict`, `fold_measure_unsupported`, `dimension_field_not_time`, and `field_not_metricable` for `avg`/`sum` over a date. A spec over the cost limit is `bucket_estimate_exceeded` (an item error inside the 200 response); `hourOfDay` costs days x 24 buckets, `dayOfWeek` days, `ageBucket` the preset size, before folding. From / To: `duration_fields_same`, `duration_field_not_date`, `duration_pair_conflict`. Per-flow and Data sources: a stored card naming a column that is gone is not a 422 but an item `error` (`field_unavailable` or `source_columns_unchecked`). Hourly grouping (`minute`/`hour` `dateHistogram`, `hourOfDay`) is an item `error`, not a 422, on per-flow and Data sources: `time_grouping_date_only` on a `date` field, `time_grouping_needs_range` on a Data `dateTime` field without a `range` filter on it of at most 31 days; the other cards of the batch run. Data sources: `data_source_id_invalid` for a bare 24-hex id. content: application/json: schema: type: object properties: status: type: boolean example: false message: type: string error: type: object properties: code: type: string description: >- Descriptive string code, e.g. `batch_too_large`, `field_unknown`, `hub_not_allowed` message: type: string field: type: string description: Offending key, when known examples: response: value: status: false message: This request carries 14 queries, but the limit is 12. error: code: batch_too_large message: This request carries 14 queries, but the limit is 12. '429': description: Too Many Requests - more than 60 requests in a minute content: application/json: schema: type: object properties: status: type: boolean example: false message: type: string description: Human-readable reason failedCode: type: string description: Structured error code, see Status Codes examples: response: value: status: false message: Too Many Attempts. failedCode: sys-036 security: - bearerAuth: [] components: securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: Use a valid Bearer token to authenticate. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.