> ## Documentation Index > Fetch the complete documentation index at: https://docsv4.mile.app/llms.txt > Use this file to discover all available pages before exploring further. # Get sample rows > Returns up to 20 sample rows of one query spec, newest first on the spec's `timeField`, so the widget composer can show the records behind a card. The preview limits rows, not columns: the columns are every available column of the source (`previewColumns` of the catalog), never chosen by the client. Task (all): flow, status, hub, label, created from, created / start / end / done / updated time, travel duration, then id, flow id, hub id, title, content, assignee, assigned by, created by, done by, done coordinate and ref id (emails included); Task - {Flow}: the same without flow, then the flow's other reserved keys, its page done times and every offered flow component (photo, signature, voice, video, bill and list never); Data - {name}: every available data type field, then created / updated time and created / updated by. Columns hidden for a role are shown too: the index decides the columns. User has no Sample rows (`422 preview_not_supported`). A Data source reads all records you can see, whatever `timeRange` says. Rows follow the same visibility as the card's numbers (organization, hub scope unless the data type is shared by every hub, soft delete, the flow of a Task - {Flow} source, the per-user restriction of a data type) and, for a role whose task access is only its own tasks, only the caller's own tasks. The caller needs `view/dashboard` and the source's `viewPermission` (`view/task` for the Task family, `view/data` for a Data source). The spec is validated like Run analytics query (same codes, including `time_grouping_needs_range` and `time_grouping_date_only`, here as 422); its measures and dimensions are not aggregated here. Rate-limited to 30 requests per minute per user, counted separately from Run analytics query. ## OpenAPI ````yaml /openapi/public/openapi-analytics.json post /analytics/preview 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/preview: post: tags: - Dashboard summary: Get sample rows description: >- Returns up to 20 sample rows of one query spec, newest first on the spec's `timeField`, so the widget composer can show the records behind a card. The preview limits rows, not columns: the columns are every available column of the source (`previewColumns` of the catalog), never chosen by the client. Task (all): flow, status, hub, label, created from, created / start / end / done / updated time, travel duration, then id, flow id, hub id, title, content, assignee, assigned by, created by, done by, done coordinate and ref id (emails included); Task - {Flow}: the same without flow, then the flow's other reserved keys, its page done times and every offered flow component (photo, signature, voice, video, bill and list never); Data - {name}: every available data type field, then created / updated time and created / updated by. Columns hidden for a role are shown too: the index decides the columns. User has no Sample rows (`422 preview_not_supported`). A Data source reads all records you can see, whatever `timeRange` says. Rows follow the same visibility as the card's numbers (organization, hub scope unless the data type is shared by every hub, soft delete, the flow of a Task - {Flow} source, the per-user restriction of a data type) and, for a role whose task access is only its own tasks, only the caller's own tasks. The caller needs `view/dashboard` and the source's `viewPermission` (`view/task` for the Task family, `view/data` for a Data source). The spec is validated like Run analytics query (same codes, including `time_grouping_needs_range` and `time_grouping_date_only`, here as 422); its measures and dimensions are not aggregated here. Rate-limited to 30 requests per minute per user, counted separately from Run analytics query. operationId: previewAnalyticsRows requestBody: content: application/json: schema: type: object required: - spec properties: specVersion: type: integer description: >- Accepted at batch level; the spec-level value is the one validated 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`. spec: type: object description: >- One query spec, exactly as an item `spec` of Run analytics query. Only the keys `specVersion`, `timeRange`, `hubIds`, `utcOffset` and `spec` are allowed at the top level (`422 unknown_key`); a missing or non-object `spec` is `422 query_spec_missing`. additionalProperties: true example: specVersion: 1 timeRange: preset: last7Days spec: specVersion: 1 dataSourceId: task timeField: startTime measures: - id: m1 fn: count filters: - field: status op: eq value: DONE required: true responses: '200': description: >- Success - `columns` in `previewColumns` order, `rows` as positional arrays (at most 20). A missing value is `null`; several values are joined with ", "; a geolocation column is the raw text "lat, lng" (for example "-6.2, 106.817"); dates are epoch milliseconds; numbers are decimals (`travelDuration` in minutes, `unit: duration`). 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' columns: type: array items: type: object properties: id: type: string description: The logical field name field: type: string description: The logical field name unit: type: string description: '`duration` for `travelDuration`, otherwise `null`' label: type: string description: >- The i18n key of the column title for a core field (e.g. `field.task.flow`, `field.data.createdTime`); the field title, shown as is, for a flow component or a data type field description: >- Every column is `{id, field, type, unit, label}`; `type` is the platform type (`option`, `text`, `date`, `dateTime`, `number`, `geolocation`). (`type` is left out of the schema on this page because the docs build rewrites keys named `type`; the API does return it.) rows: type: array items: type: array items: type: object additionalProperties: true description: >- At most 20 rows. A row never carries a storage path; the task id (`_id`), `refId` and email columns (e.g. `assignee`, `createdBy`) are shown. meta: type: object properties: limit: type: integer example: 20 returned: type: integer sort: type: object properties: field: type: string description: The spec `timeField` direction: type: string enum: - desc examples: response: value: status: true specVersion: 1 resolvedTimeRange: from: '2026-10-21T00:00:00+07:00' to: '2026-10-27T23:59:59+07:00' timezone: Asia/Jakarta preset: last7Days columns: - id: flow field: flow unit: null label: field.task.flow - id: status field: status unit: null label: field.task.status - id: startTime field: startTime unit: null label: field.task.startTime rows: - - Delivery - DONE - 1761616200000 meta: limit: 20 returned: 1 sort: field: startTime direction: desc '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 error: type: object properties: code: type: string message: type: string field: type: string '403': description: >- Forbidden - `data_source_forbidden` with top-level `failedCode` `sys-035` when the role lacks the source's `viewPermission` (`view/task` for the Task family, `view/data` for a `data:` source); `data_source_not_licensed` for a Big Data source (Task - {Flow}) in an organization without Big Data; `hub_not_allowed` when `hubIds` names a hub the caller does not belong to. A role without `view/dashboard` gets `sys-035`. No rows are returned. content: application/json: schema: type: object properties: status: type: boolean example: false message: type: string failedCode: type: string error: type: object properties: code: type: string message: type: string examples: response: value: status: false message: >- You do not have permission to view the rows of data source 'task'. failedCode: sys-035 error: code: data_source_forbidden message: >- You do not have permission to view the rows of data source 'task'. '422': description: >- Unprocessable - nothing ran. `error.code`: `unknown_key`, `query_spec_missing`, `data_source_id_invalid` (including a bare 24-hex id), `preview_not_supported` (User), `data_source_unavailable` (the source does not resolve for this organization or is unavailable, e.g. a deleted data type), `field_unavailable` / `source_columns_unchecked` (Task - {Flow} or Data column gone / not checked; `field_unavailable` also for a retired Task field such as `organizationName`), `time_grouping_needs_range` (an hourly grouping on a Data `dateTime` field without a `range` filter on it of at most 31 days), `time_grouping_date_only` (an hourly grouping on a `date` field), `time_range_exceeded` and the other cost codes, any spec validation code of Run analytics query, or `engine_error` (generic message). content: application/json: schema: type: object properties: status: type: boolean example: false message: type: string error: type: object properties: code: type: string message: type: string field: type: string '429': description: >- Too Many Requests - more than 30 sample-row requests in a minute (counted separately from Run analytics query) 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.