> ## 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.

# Create an action

> Record an action, and the savings the change it describes goes on to make.

An action resolving an "enable Automated Savings" insight joins the action
already open for that feature on the same resource rather than adding a second
one measuring the same change. The response is that action, carrying the
insight. SELECT opens that action itself when the feature is turned on, so
with none to join the create is refused with a 409.



## OpenAPI

````yaml https://api.select.dev/v2/openapi.json post /actions
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:
  /actions:
    post:
      tags:
        - actions
      summary: Create an action
      description: >-
        Record an action, and the savings the change it describes goes on to
        make.


        An action resolving an "enable Automated Savings" insight joins the
        action

        already open for that feature on the same resource rather than adding a
        second

        one measuring the same change. The response is that action, carrying the

        insight. SELECT opens that action itself when the feature is turned on,
        so

        with none to join the create is refused with a 409.
      operationId: create_action_route_actions_post
      parameters:
        - 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.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ActionCreate'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActionV2'
        '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'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/ValidationFailed'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
      security:
        - HTTPBearer: []
components:
  schemas:
    ActionCreate:
      properties:
        title:
          type: string
          maxLength: 200
          title: Title
        comment:
          anyOf:
            - type: string
            - type: 'null'
          title: Comment
        user_email:
          type: string
          minLength: 1
          title: User Email
          description: >-
            Email of the person who took this action. Defaults to the calling
            user. Required for an API key, which has no user identity. Cannot be
            `null`.
          x-doit-confidentiality: customer-data
          x-doit-pii: true
        actioned_time:
          type: string
          format: date-time
          title: Actioned Time
          description: >-
            When the action was taken, as an RFC 3339 timestamp. Defaults to
            now. Set it to backdate the action; savings are then measured from
            that day. Converted to UTC; a timestamp with no offset is read as
            UTC. Cannot be `null`.
        end_date:
          anyOf:
            - type: string
              format: date
            - type: 'null'
          title: End Date
        srn:
          anyOf:
            - type: string
              maxLength: 2048
            - type: 'null'
          title: Srn
          description: >-
            The canonical SELECT Resource Name (SRN) of the resource this action
            applies to. Resolve one from a resource's identifying details with
            `POST /v2/srn/actions/resolve`. An empty string scopes the action to
            the whole organization. Insight SRNs are rejected — name an insight
            with `insight_id` instead.
        insight_id:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          title: Insight Id
        savings_type:
          type: string
          enum:
            - manual
            - calculated
            - calculated_smart_suspend
          title: Savings Type
        savings_amount:
          anyOf:
            - type: number
            - type: 'null'
          title: Savings Amount
        savings_rate_percent:
          anyOf:
            - type: number
            - type: 'null'
          title: Savings Rate Percent
        select_feature:
          anyOf:
            - type: string
              enum:
                - smart_suspend
                - apc_automated_savings
                - dbx_warehouse_automated_savings
                - jcss_automated_savings
            - type: 'null'
          title: Select Feature
        resource_metadata:
          anyOf:
            - $ref: '#/components/schemas/ResourceMetadata'
            - type: 'null'
        team_id:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          title: Team Id
      additionalProperties: false
      type: object
      required:
        - title
        - savings_type
      title: ActionCreate
      description: >-
        Create a cost-saving action.


        Name the resource the action applies to with exactly one of `srn` or

        `insight_id`. If you have the resource's identifying details but not its

        SRN, resolve one first with `POST /v2/srn/actions/resolve`. An action on
        an

        insight must name it with `insight_id`.


        `user_email` defaults to the calling user. `actioned_time` defaults to
        now;

        set it to backdate the action. An API key has no user identity, so a

        key-authenticated caller must set `user_email`.
    ActionV2:
      properties:
        id:
          type: string
          title: Id
        title:
          type: string
          title: Title
        srn:
          type: string
          title: Srn
        comment:
          anyOf:
            - type: string
            - type: 'null'
          title: Comment
        user_email:
          type: string
          title: User Email
          x-doit-confidentiality: customer-data
          x-doit-pii: true
        actioned_time:
          type: string
          title: Actioned Time
        end_date:
          anyOf:
            - type: string
              format: date
            - type: 'null'
          title: End Date
        insight_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Insight Id
        insight_type:
          anyOf:
            - type: string
            - type: 'null'
          title: Insight Type
        savings_type:
          anyOf:
            - type: string
              enum:
                - calculated
                - manual
            - type: 'null'
          title: Savings Type
        savings_amount:
          anyOf:
            - type: number
            - type: 'null'
          title: Savings Amount
        savings_rate_percent:
          anyOf:
            - type: number
            - type: 'null'
          title: Savings Rate Percent
        savings_override_percent:
          anyOf:
            - type: number
            - type: 'null'
          title: Savings Override Percent
        ignore_tgs_floor:
          type: boolean
          title: Ignore Tgs Floor
          default: false
        current_daily_savings:
          anyOf:
            - type: number
            - type: 'null'
          title: Current Daily Savings
          readOnly: true
          x-terraform-computed: true
        current_annualized_savings:
          anyOf:
            - type: number
            - type: 'null'
          title: Current Annualized Savings
          readOnly: true
          x-terraform-computed: true
        current_realized_savings:
          anyOf:
            - type: number
            - type: 'null'
          title: Current Realized Savings
          readOnly: true
          x-terraform-computed: true
        savings_status:
          anyOf:
            - type: string
              enum:
                - pending
                - calculated
                - error
                - unsupported
            - type: 'null'
          title: Savings Status
        savings_calculation_metadata:
          anyOf:
            - $ref: '#/components/schemas/SavingsCalculationMetadata'
            - type: 'null'
        savings_materialized_through:
          anyOf:
            - type: string
              format: date
            - type: 'null'
          title: Savings Materialized Through
        select_feature:
          anyOf:
            - type: string
              enum:
                - smart_suspend
                - apc_automated_savings
                - dbx_warehouse_automated_savings
                - jcss_automated_savings
            - type: 'null'
          title: Select Feature
        resource_metadata:
          anyOf:
            - $ref: '#/components/schemas/ResourceMetadata'
            - type: 'null'
        team_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Team Id
        created_by:
          type: string
          title: Created By
          x-doit-confidentiality: customer-data
          x-doit-pii: true
        updated_by:
          anyOf:
            - type: string
            - type: 'null'
          title: Updated By
          x-doit-confidentiality: customer-data
          x-doit-pii: true
        srn_resource_type:
          type: string
          title: Srn Resource Type
        create_time:
          type: string
          title: Create Time
        update_time:
          type: string
          title: Update Time
        etag:
          type: string
          title: Etag
          description: Opaque strong ETag.
          readOnly: true
          x-terraform-computed: true
      type: object
      required:
        - id
        - title
        - srn
        - user_email
        - actioned_time
        - created_by
        - srn_resource_type
        - create_time
        - update_time
        - etag
      title: Action
      description: >-
        A cost-saving action taken on a Snowflake resource, with its measured
        savings.
    ResourceMetadata:
      properties:
        resource_type:
          anyOf:
            - type: string
            - type: 'null'
          title: Resource Type
        identifying_metadata:
          additionalProperties: true
          type: object
          title: Identifying Metadata
        account_metadata:
          additionalProperties: true
          type: object
          title: Account Metadata
      type: object
      title: ResourceMetadata
    SavingsCalculationMetadata:
      properties:
        avg_daily_before:
          type: number
          title: Avg Daily Before
        avg_daily_after:
          type: number
          title: Avg Daily After
        savings_per_day:
          type: number
          title: Savings Per Day
        after_period_start:
          type: string
          title: After Period Start
        after_period_end:
          type: string
          title: After Period End
        before_period_start:
          type: string
          title: Before Period Start
        before_period_end:
          type: string
          title: Before Period End
        days_in_period:
          type: integer
          title: Days In Period
        sum_spend_before:
          type: number
          title: Sum Spend Before
        sum_spend_after:
          type: number
          title: Sum Spend After
        calculated_at:
          type: string
          title: Calculated At
        savings_rate_percent:
          anyOf:
            - type: number
            - type: 'null'
          title: Savings Rate Percent
        was_capped:
          type: boolean
          title: Was Capped
          default: false
        eligibility:
          anyOf:
            - $ref: '#/components/schemas/EligibilityResult'
            - type: 'null'
        override:
          anyOf:
            - $ref: '#/components/schemas/OverrideInfo'
            - type: 'null'
      type: object
      required:
        - avg_daily_before
        - avg_daily_after
        - savings_per_day
        - after_period_start
        - after_period_end
        - before_period_start
        - before_period_end
        - days_in_period
        - sum_spend_before
        - sum_spend_after
        - calculated_at
      title: SavingsCalculationMetadata
    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:
          $ref: '#/components/schemas/ErrorCode'
        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
    EligibilityResult:
      properties:
        eligible:
          type: boolean
          title: Eligible
        reasons:
          items:
            type: string
          type: array
          title: Reasons
        insufficient_spend:
          type: boolean
          title: Insufficient Spend
          default: false
        bytes_diff_pct:
          anyOf:
            - type: number
            - type: 'null'
          title: Bytes Diff Pct
        query_diff_pct:
          anyOf:
            - type: number
            - type: 'null'
          title: Query Diff Pct
        config_changes:
          anyOf:
            - type: integer
            - type: 'null'
          title: Config Changes
        multi_cluster:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Multi Cluster
        prior_savings:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Prior Savings
      type: object
      required:
        - eligible
      title: EligibilityResult
      description: >-
        Whether an action qualifies for percentage-of-spend savings and the
        indicators behind that decision.
    OverrideInfo:
      properties:
        applied_percent:
          type: number
          title: Applied Percent
        original_reasons:
          items:
            type: string
          type: array
          title: Original Reasons
      type: object
      required:
        - applied_percent
      title: OverrideInfo
      description: >-
        A manually applied savings percentage override and the original
        ineligibility reasons.
    ErrorCode:
      type: string
      enum:
        - validation_failed
        - unauthorized
        - invalid_token
        - forbidden
        - not_found
        - tenant_id_required
        - tenant_mismatch
        - conflict
        - delete_blocked_by_dependencies
        - query_profile_unavailable
        - insight_auto_closed
        - integration_credentials_rejected
        - describe_procedure_unavailable
        - missing_grant
        - monitor_run_without_period
        - template_render_failed
        - response_too_large
        - precondition_failed
        - precondition_required
        - quota_exceeded
        - rate_limited
        - filter_key_not_supported
        - pagination_token_expired
        - pagination_token_invalid
        - internal_error
        - service_unavailable
      title: ErrorCode
      description: >-
        The machine-readable identifier of an error.


        Clients branch on this, never on ``title`` or ``detail``. A published
        code keeps

        its meaning; new codes may be added.
  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'
    Conflict:
      description: Conflict
      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

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.