> ## Documentation Index
> Fetch the complete documentation index at: https://docs.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: status, role id, role name, team id, hub, email, name, language, first login (`true` / `false`), user id, created / verified / updated time and last login; team and hub cells stay ids (several values joined with ", "), the response carries `valueLabels` with their names, and a hub cell lists only the caller's hubs when the caller is limited to some hubs. No secret or contact field of a user (phone number, avatar, activation code, authenticator) is ever returned. Routing Result: result name, result code, status, dispatch status, created from, hub, created by, created / finish / updated time, then the eleven run numbers (distance in metres, the four times in minutes); hub and created by cells stay ids and the response carries `valueLabels` with their names. Hidden and deleted runs are never returned. 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/user` for User, `view/result` for Routing Result, `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. 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/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:
        status, role id, role name, team id, hub, email, name, language, first
        login (`true` / `false`), user id, created / verified / updated time and
        last login; team and hub cells stay ids (several values joined with ",
        "), the response carries `valueLabels` with their names, and a hub cell
        lists only the caller's hubs when the caller is limited to some hubs. No
        secret or contact field of a user (phone number, avatar, activation
        code, authenticator) is ever returned. Routing Result: result name,
        result code, status, dispatch status, created from, hub, created by,
        created / finish / updated time, then the eleven run numbers (distance
        in metres, the four times in minutes); hub and created by cells stay ids
        and the response carries `valueLabels` with their names. Hidden and
        deleted runs are never returned. 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/user` for User, `view/result` for Routing Result,
        `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. 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: 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
                  valueLabels:
                    type: object
                    description: >-
                      Users source (`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). Routing Result (`routing_result`): names for `hub`
                      (from hubs) and `createdBy` (from users), read the same
                      way. 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-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/user` for `user`,
            `view/result` for `routing_result`, `view/data` for a
            `data:<dataTypeId>` 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` (a source without Sample rows),
            `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`),
            `team_scope_unresolved` (Task sources only: the caller's team
            members could not be resolved, so nothing ran; retryable),
            `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.