> ## 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. # Read dashboards > Retrieves a paginated list of the dashboards visible to the caller: the ones they created plus the ones shared with their role. List rows do not include card widget definitions; use Read dashboard by ID to get them. ## OpenAPI ````yaml /openapi/public/openapi-analytics.json get /dynamic-dashboards openapi: 3.0.0 info: title: MileApp API - Analytics version: 3.0.0 description: MileApp 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. paths: /dynamic-dashboards: get: tags: - Dashboard summary: Read dashboards description: >- Retrieves a paginated list of the dashboards visible to the caller: the ones they created plus the ones shared with their role. List rows do not include card widget definitions; use Read dashboard by ID to get them. operationId: listDynamicDashboards parameters: - name: name in: query required: false description: Case-insensitive substring match on the dashboard name schema: type: string maxLength: 200 - name: scope in: query required: false description: >- `mine` = created by the caller; `shared` = shared with the caller's role and created by someone else; `all` = both schema: type: string enum: - all - mine - shared default: all - name: limit in: query required: false description: Page size schema: type: integer minimum: 1 maximum: 100 default: 20 - name: page in: query required: false description: Page number schema: default: 1 type: integer - name: sortOrder in: query required: false description: Sort direction on `updatedTime` schema: type: string enum: - ASC - DESC - asc - desc default: DESC responses: '200': description: Success - paginated list content: application/json: schema: type: object properties: status: type: boolean example: true code: type: integer message: type: string data: type: object properties: current_page: type: integer data: type: array items: type: object properties: _id: type: string organizationId: type: string description: Stamped from the caller's session; immutable schemaVersion: type: integer example: 1 name: type: string description: type: string sharedRoleIds: type: array items: type: string description: >- The whole sharing state: empty = only the owner, non-empty = those roles as well (read-only for them) hubScope: type: object properties: mode: type: string enum: - all - selected description: Required whenever `hubScope` is sent hubIds: type: array maxItems: 200 items: type: string timeRange: type: object description: >- Default time window for the dashboard, or `null`. Not interpreted by the CRUD layer; the analytics endpoint accepts `today`, `yesterday`, `last_7d`, `last_30d`. properties: preset: type: string maxLength: 50 grid: type: object properties: columns: type: integer minimum: 1 maximum: 48 description: >- Column count, default 12. Stored per document. engine: type: string enum: - flow - absolute description: Optional layout engine hint widgets: type: array items: type: object description: >- A card on a dashboard. Stored cards carry only the reference; `widget` is attached on read. properties: cardId: type: string description: >- Stable card id `crd_` followed by a ULID, assigned by the server. Also the batch key of the analytics request. widgetId: type: string description: The `dynamicWidgets` row this card owns widgetName: type: string description: Label that follows the row's name layout: type: object description: Card placement on the grid properties: w: type: integer minimum: 2 description: >- Width in grid columns, 2 to `grid.columns` h: type: integer minimum: 3 maximum: 18 description: >- Height in rows, 3-18; `null` = as tall as its content x: type: integer minimum: 0 maximum: 48 description: >- Optional column offset (free placement accepted, not required) 'y': type: integer minimum: 0 description: Optional row offset widget: type: object description: >- A widget definition (a `dynamicWidgets` row without identity and audit fields) properties: schemaVersion: type: integer example: 1 name: type: string maxLength: 200 description: Literal display name, never translated description: type: string category: type: string enum: - overview - taskStatus - productivity - timeDuration - team - hub - trend - utility viz: type: string description: >- Visualization: kpi, bar, line, donut, table, heatmap, text, banner spec: type: object description: >- Neutral analytics query spec executed by POST /analytics/query. See Run analytics query for the full grammar. properties: specVersion: type: integer dataSourceId: type: string timeField: type: string measures: type: array items: type: object additionalProperties: true dimensions: type: array items: type: object additionalProperties: true filters: type: array items: type: object additionalProperties: true composite: type: object description: >- Multi-query widget `{kind, queries: {key: spec}}`; `null` for ordinary widgets additionalProperties: true content: type: object description: >- `{body}` for text and banner widgets; `null` otherwise properties: body: type: string maxLength: 2000 defaultLayout: type: object description: Card placement on the grid properties: w: type: integer minimum: 2 description: >- Width in grid columns, 2 to `grid.columns` h: type: integer minimum: 3 maximum: 18 description: >- Height in rows, 3-18; `null` = as tall as its content x: type: integer minimum: 0 maximum: 48 description: >- Optional column offset (free placement accepted, not required) 'y': type: integer minimum: 0 description: Optional row offset origin: type: object description: Provenance only; nothing dereferences `sourceId` properties: kind: type: string enum: - blank - template - duplicate - dashboard sourceId: type: string sourceSchemaVersion: type: integer copiedAt: type: string format: date-time createdBy: type: string description: >- Owner's email. Only the owner may PATCH or DELETE. updatedBy: type: string createdTime: type: string format: date-time updatedTime: type: string format: date-time description: >- Echo this back on PATCH as the lost-update precondition per_page: type: integer total: type: integer last_page: type: integer from: type: integer to: type: integer next_page_url: type: string prev_page_url: type: string examples: response: value: status: true code: 200 message: Success. data: current_page: 1 data: - _id: 66f9a1c2e4b0a7d3c1f20a11 organizationId: 6650c2a1f3b9e4001c7d2a10 schemaVersion: 1 name: Jakarta Hub - Daily description: Morning stand-up view sharedRoleIds: - 6650c2a1f3b9e4001c7d2b20 hubScope: mode: selected hubIds: - 6650c2a1f3b9e4001c7d2c30 timeRange: preset: last_7d grid: columns: 12 widgets: - cardId: crd_01J8ZQ4R5W6X7Y8Z9A0B1C2D3E widgetId: 66f9a1c2e4b0a7d3c1f20b01 widgetName: Total Tasks layout: w: 3 h: null - cardId: crd_01J8ZQ4R5W6X7Y8Z9A0B1C2D3F widgetId: 66f9a1c2e4b0a7d3c1f20b02 widgetName: Tasks by Status layout: w: 6 h: 6 x: 3 'y': 0 origin: kind: blank sourceId: null sourceSchemaVersion: null copiedAt: '2026-09-30T08:10:44+07:00' createdBy: ops.lead@example.com updatedBy: ops.lead@example.com createdTime: '2026-09-30T01:10:44.512000Z' updatedTime: '2026-09-30T01:15:02.481000Z' first_page_url: https://apiweb.mile.app/api/v3/dynamic-dashboards?page=1 from: 1 last_page: 1 last_page_url: https://apiweb.mile.app/api/v3/dynamic-dashboards?page=1 next_page_url: null path: https://apiweb.mile.app/api/v3/dynamic-dashboards per_page: 20 prev_page_url: null to: 1 total: 1 '400': description: >- Bad Request - invalid query parameter (e.g. `scope` outside the enum is `dydsh-017`, `limit` out of range is `dydsh-009`) 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: >- The selected `scope` is invalid. Please select from the available options. failedCode: dydsh-017 '401': description: Unauthorized - missing, invalid or expired access token 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 - the caller's role lacks `view/dashboard` 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: >- Access denied. You do not have permission for view dashboard. Please contact your admin to request access. failedCode: sys-035 '500': description: Server Error - unexpected exception, logged server-side 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 code: type: integer description: >- HTTP status repeated in the body (repository failures only) data: type: array items: type: object additionalProperties: true description: Empty on most failures examples: response: value: status: false code: 500 message: something_wrong failedCode: dydsh-045 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.