> ## Documentation Index
> Fetch the complete documentation index at: https://api-docs.select.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# List a dashboard's digests

> Lists the scheduled digests configured on a dashboard, newest first.



## OpenAPI

````yaml https://api.select.dev/v2/openapi.json get /dashboards/{dashboard_id}/digests
openapi: 3.1.0
info:
  title: SELECT API (v2)
  version: 0.1.0
servers:
  - url: https://api.select.dev/v2
    description: SELECT API v2
security: []
tags:
  - name: metrics
    description: >-
      Query cost and usage data across Snowflake, BigQuery, Databricks and
      Tableau. Each route is `POST /v2/metrics/<model>/query` for one semantic
      model. Every route takes the same body shape and returns the same response
      shape. Each route page gives guidance on when to use the route, and worked
      examples.


      ## Body shape


      | Field | Meaning |

      | --- | --- |

      | `measures` | Aggregates to compute, for example `sum_spend`. |

      | `dimensions` | Fields to group by. Each one is returned on every row. |

      | `filter_expression` | An `and`/`or` tree of filters on dimensions,
      applied before aggregation. |

      | `measure_filters` | Filters on measures, applied after aggregation. |

      | `sort` | The order of the rows: `[{"field": "sum_spend", "direction":
      "desc"}]`. |

      | `limit` | The maximum number of rows. Results are not paginated: `limit`
      cuts the result short, and there is no next page. Omit `limit` to get all
      rows. |

      | `aggregate` | Set `false` to list the rows with no grouping. See
      "Listing rows". |


      v2 accepts only `filter_expression`. The body refuses the legacy `filters`
      list.


      ## Filter on dates


      Filter on the `day` field. Use two filters (both bounds are inclusive):


      ```json

      {"operator": "and", "filters": [
        {"field": "day", "operator": ">=", "value": "2026-08-01"},
        {"field": "day", "operator": "<=", "value": "2026-08-31"}], "limit": 1000}
      ```


      Or use one relative filter: `{"field": "day", "operator": "in range",
      "value": "30D"}`. The values are `{N}D` and `{N}M` (the last N days or
      months, today included), `WTD`, `MTD`, `QTD`, `YTD`, and `LMTD` (the whole
      previous calendar month).


      - Do not filter on `hour`, `week`, `month` or `quarter` to bound a range.
      Filter on `day`, and use the coarser fields as dimensions.

      - A timestamp such as `start_time <= "2026-08-31"` compares to midnight
      and drops most of that day. Use `day`, or `start_time < "2026-09-01"`.

      - A snapshot route (for example `snowflake-storage-summary`) describes the
      current state, and a `day` filter does not bound its size and cost fields.
      On routes that join the snapshot to activity, `day` bounds only the
      activity fields. Each route page says which fields these are.


      ## Which measure is cost


      - `sum_spend` (or `spend`, or `cost` on some routes) is the dollar cost in
      the filtered period. Use it for "how much did we spend".

      - `*_annualized` measures extend the spend of the filtered period to a
      year: a `7D` range gives that week's spend times 365 / 7. They are
      projections, not spend.

      - On snapshot routes, `annual_cost`, `*_monthly_cost` and `*_annual_cost`
      are the current rate extended to a month or a year. A date range does not
      bound them.

      - Do not present any of these run-rates as spend in a period.

      - Databricks routes also give DBUs (for example `sum_task_usage`). DBUs
      are not dollars.


      The `spend` route is the consolidated cost of every platform. Use it for
      totals, trends and breakdowns by service. Use a platform route to explain
      what inside the platform caused the cost.


      ## Text values are case-sensitive


      Filter values must match the stored case. A value in the wrong case
      matches no rows, with no error. For example:


      - On `spend`, `connection_type` is `Snowflake`, `Bigquery` or
      `Databricks`, and `"snowflake"` matches nothing.

      - On `search`, `data-freshness` and `workload-metadata-suggestions`,
      `connection_type` is lowercase: `snowflake`, `bigquery`, `databricks`.

      - On `snowflake-workloads`, most `resource_type` values are lowercase keys
      (`query_pattern`, `dbt`), but the AI types are title case (`Cortex
      Analyst`).


      ## Usage groups


      A usage group set divides cost into named groups, such as departments or
      teams. To group by the groups of one set, name the set in `path`:


      ```json

      {"dimensions": [{"field": "usage_group", "path": ["Department"]}],
      "limit": 1000}

      ```


      `path[0]` is the name of the set, not its ID. A plain `"usage_group"`
      dimension groups by every set at once. The same `{"field": ..., "path":
      [...]}` form reads keys of other semi-structured fields, for example
      workload metadata.


      ## Period over period


      Some routes publish `<measure>_previous_period`, `change_<measure>` and
      `percent_change_<measure>`. These measures need one bounded date range on
      `day`, at the top level of `filter_expression`:


      - Use two bounds on `day`, or one `in range` filter. Do not mix the two
      forms.

      - Do not nest the date filter in a sub-expression, and do not bound the
      range with `month` or `quarter`.

      - The previous period is the same number of days, just before the range.
      For `QTD` on 2026-09-28 (2026-07-01 to 2026-09-28, 90 days), the previous
      period is 2026-04-02 to 2026-06-30, not the previous calendar quarter.


      ## Listing rows


      Set `"aggregate": false` and name only `dimensions` to get the rows as
      they are, for example the individual queries that ran longer than ten
      minutes. If the body also names `measures` or `measure_filters`, the route
      aggregates, with no error. Always set a `limit` on a listing.


      ## Default scoping filters


      Some tables hold more than one kind of row, and the SELECT app filters to
      one kind by default. Each route page names these filters. For example:


      - `snowflake-query-patterns`: `{"field": "resource_type", "operator":
      "in", "values": ["query_pattern"]}`. `bigquery-query-patterns` filters
      `workload_type` to `bigquery_query_pattern`, and
      `databricks-query-patterns` filters `resource_type` to
      `databricks_query_pattern`.

      - `snowflake-dbt`: `{"field": "dbt_node_resource_type", "operator": "=",
      "value": "model"}`. Without it, tests, seeds and snapshots rank with
      models. The same filter applies to `bigquery-dbt-queries` and
      `databricks-dbt-queries`.


      ## Teams


      Send `X-Team-Id` to evaluate a query as a team you belong to. The rows are
      then limited to what the team's roles can reach.


      ## Which route answers which question


      | Question | Route |

      | --- | --- |

      | Total spend, spend trend, spend by platform, service or usage group |
      `spend` |

      | Most expensive Snowflake warehouses | `snowflake-workloads` (or
      `snowflake-warehouses` for metering spend) |

      | Warehouse utilization, idle spend, cluster usage |
      `snowflake-warehouses`, `snowflake-warehouse-clusters` |

      | Query latency, spillage and bytes scanned on a warehouse |
      `snowflake-warehouse-query-performance` |

      | Most expensive recurring queries | `snowflake-query-patterns` |

      | Individual queries | `snowflake-queries` |

      | Cost of dbt models, and of dbt runs | `snowflake-dbt`,
      `snowflake-dbt-invocations` |

      | Cost of tasks, stored procedures, dynamic tables | `snowflake-tasks`,
      `snowflake-stored-procedures`, `snowflake-dynamic-tables` |

      | Cost of BI tools (Looker, Mode, Hex, Sigma, Periscope, Tableau) |
      `snowflake-looker`, `snowflake-mode`, `snowflake-hex`, `snowflake-sigma`,
      `snowflake-periscope`, `tableau-queries` |

      | Cost of Fivetran, and of workloads defined by query tags |
      `snowflake-fivetran`, `snowflake-custom-workloads` |

      | Serverless, automatic clustering and Snowpipe cost |
      `snowflake-serverless`, `snowflake-automatic-clustering`,
      `snowflake-snowpipe` |

      | Storage cost in a period | `snowflake-storage`, `bigquery-storage-spend`
      |

      | Largest or unused tables now | `snowflake-storage-summary`,
      `bigquery-storage-summary` |

      | Which workloads read or write a table | `lineage-workloads`,
      `lineage-tables`, `lineage-edges` |

      | BigQuery cost by project, job or query pattern | `bigquery-projects`,
      `bigquery-jobs`, `bigquery-query-patterns` |

      | BigQuery reservations and commitments | `bigquery-reservation-timeline`,
      `bigquery-commitments`, `bigquery-commitment-scopes` |

      | Databricks cost by job, query, SQL warehouse or cluster |
      `databricks-jobs`, `databricks-queries`, `databricks-sql-warehouses`,
      `databricks-clusters` |

      | Savings from SELECT actions | `action-realized-savings` |

      | How current the data is | `data-freshness` |
paths:
  /dashboards/{dashboard_id}/digests:
    get:
      tags:
        - dashboards
      summary: List a dashboard's digests
      description: Lists the scheduled digests configured on a dashboard, newest first.
      operationId: list_dashboard_digests_route_dashboards__dashboard_id__digests_get
      parameters:
        - name: dashboard_id
          in: path
          required: true
          schema:
            type: string
            title: Dashboard Id
        - name: page_token
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: Opaque cursor from a previous response. Omit on the first call.
            title: Page Token
          description: Opaque cursor from a previous response. Omit on the first call.
        - name: max_results
          in: query
          required: false
          schema:
            type: integer
            default: 50
            title: Max Results
        - name: x-tenant-id
          in: header
          required: true
          schema:
            type: string
            description: The organization ID the request is scoped to.
            title: X-Tenant-Id
          description: The organization ID the request is scoped to.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListResponse_DashboardDigestV2_'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '408':
          $ref: '#/components/responses/RequestTimeout'
        '422':
          $ref: '#/components/responses/ValidationFailed'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
      security:
        - HTTPBearer: []
components:
  schemas:
    ListResponse_DashboardDigestV2_:
      properties:
        items:
          items:
            $ref: '#/components/schemas/DashboardDigestV2'
          type: array
          title: Items
        page_token:
          anyOf:
            - type: string
            - type: 'null'
          title: Page Token
          description: Opaque cursor for the next page; empty/absent on the last page.
        row_count:
          anyOf:
            - type: integer
            - type: 'null'
          title: Row Count
          description: >-
            Best-effort total for the filtered result set; may be null when
            expensive.
      type: object
      required:
        - items
      title: ListResponse[DashboardDigestV2]
    DashboardDigestV2:
      properties:
        id:
          type: string
          title: Id
          description: The unique identifier of the digest.
          readOnly: true
          x-terraform-computed: true
        dashboard_id:
          type: string
          title: Dashboard Id
          description: The dashboard this digest captures and delivers.
          readOnly: true
          x-terraform-computed: true
        name:
          type: string
          title: Name
          description: The display name of the digest.
        custom_message:
          anyOf:
            - type: string
            - type: 'null'
          title: Custom Message
          description: A message included alongside the delivered dashboard.
        schedule:
          oneOf:
            - $ref: '#/components/schemas/DailySchedule'
            - $ref: '#/components/schemas/WeeklySchedule'
            - $ref: '#/components/schemas/MonthlySchedule'
          title: Schedule
          description: How often the digest is delivered.
          discriminator:
            propertyName: frequency
            mapping:
              daily:
                $ref: '#/components/schemas/DailySchedule'
              monthly:
                $ref: '#/components/schemas/MonthlySchedule'
              weekly:
                $ref: '#/components/schemas/WeeklySchedule'
        delivery_format:
          type: string
          enum:
            - pdf
            - png
            - url
          title: Delivery Format
          description: The format the dashboard is captured and delivered in.
        state:
          type: string
          enum:
            - active
            - paused
          title: State
          description: Whether the digest is actively delivering on its schedule or paused.
          default: active
        filters:
          anyOf:
            - items: {}
              type: array
            - type: 'null'
          title: Filters
          description: >-
            Filters applied to the dashboard when it is captured, in place of
            the dashboard's own saved filters. Omit this field or set it to null
            to capture the dashboard with its saved filters; set it to an empty
            array to capture the dashboard with no filters at all. Each entry
            names a field, an operator, and the value or values to compare
            against, and entries are combined with AND; an entry may instead be
            an `and`/`or` group containing its own entries in the same form. The
            operators available are the ones the dashboard's filter controls
            offer. A filter naming a field that none of the dashboard's blocks
            expose has no effect on the capture.
          examples:
            - - field: warehouse_name
                operator: in
                values:
                  - TRANSFORMING
              - field: user_name
                operator: is not
              - filters:
                  - field: database_name
                    operator: in
                    values:
                      - ANALYTICS
                  - field: database_name
                    operator: in
                    values:
                      - RAW
                operator: or
        destination_ids:
          items:
            type: string
          type: array
          title: Destination Ids
          description: The destinations the digest delivers to.
        destinations:
          items:
            $ref: '#/components/schemas/DigestDestination'
          type: array
          title: Destinations
          description: The destinations the digest delivers to, with display details.
          readOnly: true
          x-terraform-computed: true
        latest_run:
          anyOf:
            - $ref: '#/components/schemas/LatestDigestRun'
            - type: 'null'
          description: The most recent attempt to run this digest, if any.
          readOnly: true
          x-terraform-computed: true
        created_by:
          type: string
          title: Created By
          description: The identifier of the user or API key that created the digest.
          readOnly: true
          x-doit-confidentiality: customer-data
          x-doit-pii: true
          x-terraform-computed: true
        create_time:
          type: string
          title: Create Time
          description: When the digest was created, as an RFC 3339 UTC timestamp.
          readOnly: true
          x-terraform-computed: true
        update_time:
          type: string
          title: Update Time
          description: When the digest was last changed, as an RFC 3339 UTC timestamp.
          readOnly: true
          x-terraform-computed: true
        etag:
          type: string
          title: Etag
          description: >-
            Opaque strong ETag. Supply it in an If-Match header when changing or
            deleting the digest.
          readOnly: true
          x-terraform-computed: true
      type: object
      required:
        - id
        - dashboard_id
        - name
        - schedule
        - delivery_format
        - destination_ids
        - destinations
        - created_by
        - create_time
        - update_time
        - etag
      title: DashboardDigest
      description: A schedule that captures a dashboard and delivers it to destinations.
    ProblemDetail:
      additionalProperties: true
      description: >-
        RFC 9457-style error payload, served as ``application/problem+json``.


        ``code`` is the stable, machine-readable identifier — consumers branch
        on it,

        never on ``title``. ``type`` stays ``about:blank``: we keep no per-error

        documentation pages. There is no ``instance``/request-id member (we
        don't run

        access logs). See the flat error-code catalogue in §4 of the standards
        doc.
      properties:
        type:
          default: about:blank
          title: Type
          type: string
        title:
          type: string
          title: Title
        status:
          title: Status
          type: integer
        detail:
          title: Detail
          type: string
        code:
          title: Code
          type: string
        retryable:
          title: Retryable
          type: boolean
        details:
          anyOf:
            - items:
                additionalProperties: true
                type: object
              type: array
            - type: 'null'
          default: null
          title: Details
      required:
        - title
        - status
        - detail
        - code
        - retryable
      title: ProblemDetail
      type: object
    DailySchedule:
      properties:
        frequency:
          type: string
          const: daily
          title: Frequency
      type: object
      required:
        - frequency
      title: DailySchedule
    WeeklySchedule:
      properties:
        frequency:
          type: string
          const: weekly
          title: Frequency
        day_of_week:
          type: string
          enum:
            - monday
            - tuesday
            - wednesday
            - thursday
            - friday
            - saturday
            - sunday
          title: Day Of Week
      type: object
      required:
        - frequency
        - day_of_week
      title: WeeklySchedule
    MonthlySchedule:
      properties:
        frequency:
          type: string
          const: monthly
          title: Frequency
        day_of_month:
          type: integer
          maximum: 31
          minimum: 1
          title: Day Of Month
      type: object
      required:
        - frequency
        - day_of_month
      title: MonthlySchedule
    DigestDestination:
      properties:
        id:
          type: string
          title: Id
          description: The unique identifier of the destination.
          readOnly: true
          x-terraform-computed: true
        type:
          type: string
          enum:
            - slack
            - ms_teams_webhook
            - email
          title: Type
          description: The kind of destination this is.
          readOnly: true
          x-terraform-computed: true
        label:
          type: string
          title: Label
          description: >-
            A human-readable identifier for the destination — a Slack or MS
            Teams channel name, or an email address.
          readOnly: true
          x-doit-confidentiality: customer-data
          x-doit-pii: true
          x-terraform-computed: true
      type: object
      required:
        - id
        - type
        - label
      title: DigestDestination
      description: A destination a digest delivers to, as it appears on the digest.
    LatestDigestRun:
      properties:
        id:
          type: string
          title: Id
          description: The unique identifier of the run.
          readOnly: true
          x-terraform-computed: true
        status:
          type: string
          enum:
            - running
            - success
            - failure
          title: Status
          description: Whether the run is in progress, succeeded, or failed.
          readOnly: true
          x-terraform-computed: true
        start_time:
          type: string
          title: Start Time
          description: When the run started, as an RFC 3339 UTC timestamp.
          readOnly: true
          x-terraform-computed: true
        end_time:
          anyOf:
            - type: string
            - type: 'null'
          title: End Time
          description: >-
            When the run finished, as an RFC 3339 UTC timestamp. Null while the
            run is in progress.
          readOnly: true
          x-terraform-computed: true
        scheduled_date:
          type: string
          title: Scheduled Date
          description: The date (UTC) this run was scheduled for, as YYYY-MM-DD.
          readOnly: true
          x-terraform-computed: true
      type: object
      required:
        - id
        - status
        - start_time
        - scheduled_date
      title: DigestRun
      description: The most recent attempt to run a digest.
  responses:
    BadRequest:
      description: Bad request
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetail'
    Unauthorized:
      description: Unauthorized
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetail'
      headers:
        WWW-Authenticate:
          description: Authentication challenge for the requested resource.
          required: true
          schema:
            type: string
    Forbidden:
      description: Forbidden
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetail'
    NotFound:
      description: Not found
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetail'
    MethodNotAllowed:
      description: Method not allowed
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetail'
      headers:
        Allow:
          description: HTTP methods supported by the requested resource.
          required: true
          schema:
            type: string
    RequestTimeout:
      description: Request Timeout
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetail'
    ValidationFailed:
      description: Validation failed
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetail'
    RateLimited:
      description: Rate limited
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetail'
      headers:
        Retry-After:
          description: Number of seconds to wait before retrying the request.
          required: true
          schema:
            type: integer
            minimum: 0
    InternalError:
      description: Internal error
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetail'
    ServiceUnavailable:
      description: Service unavailable
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetail'
      headers:
        Retry-After:
          description: Number of seconds to wait before retrying the request.
          required: true
          schema:
            type: integer
            minimum: 0
  securitySchemes:
    HTTPBearer:
      type: http
      description: Organization API key (sl_…).
      scheme: bearer

````