Metrics

Overview

The metrics routes give the cost and usage data that the SELECT app shows, for Snowflake, BigQuery, Databricks and Tableau. Each route queries one semantic model:

POST https://api.select.dev/v2/metrics/<model>/query

All metrics routes use the same request body and the same response. When you know how to query one model, you can query all of them. Only the field names change from model to model. The reference page of each route lists its fields, and gives worked examples. This page uses the spend model for all examples. spend is the consolidated cost of all your platforms, for all services. Use it first for all questions about cost. Use a platform route (for example snowflake-workloads or bigquery-projects) to find which resource in the platform caused the cost. An API key must have the usage_data:read scope to use the metrics routes.

Your first query

This request gets the daily spend for each platform for the last 30 days:

curl https://api.select.dev/v2/metrics/spend/query \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "x-tenant-id: org_YOUR_ORG_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "measures": ["sum_spend"],
    "dimensions": ["day", "connection_type"],
    "filter_expression": {
      "operator": "and",
      "filters": [{"field": "day", "operator": "in range", "value": "30D"}]
    },
    "sort": [{"field": "day", "direction": "asc"}],
    "limit": 1000
  }'

The response has one row for each combination of day and connection_type:

{
  "items": [
    {"day": "2026-09-01", "connection_type": "Snowflake", "sum_spend": 1520.34},
    {"day": "2026-09-01", "connection_type": "Bigquery", "sum_spend": 410.02},
    {"day": "2026-09-02", "connection_type": "Snowflake", "sum_spend": 1498.77}
  ],
  "page_token": null,
  "row_count": 3,
  "sql": null
}

Request body

Field	Meaning
`measures`	The values to calculate, for example `sum_spend`.
`dimensions`	The fields to group by.
`filter_expression`	Filters on dimensions. SELECT applies them before it calculates the measures.
`measure_filters`	Filters on measures. SELECT applies them after it calculates the measures.
`sort`	The order of the rows.
`limit`	The maximum number of rows.
`aggregate`	Set to `false` to get rows with no grouping. See Listing rows.
`return_sql`	Set to `true` to get the SQL that SELECT ran, in the `sql` field of the response.

Measures

A measure is a value that SELECT calculates across a group of rows, for example a sum or an average. The name of a measure usually tells you how SELECT calculates it: sum_spend is the sum of spend, and avg_daily_spend is the average spend per day. If a request has measures and no dimensions, the response has one row: the total for all rows that match the filters.

{
  "measures": ["sum_spend"],
  "filter_expression": {
    "operator": "and",
    "filters": [{"field": "day", "operator": "in range", "value": "MTD"}]
  }
}

Measures that end in _annualized are projections, not spend. SELECT extends the spend of the filtered period to one year. For example, with a 7-day range, sum_spend_annualized is the spend of that week × 365 / 7. Do not show a projection as the spend of a period.

Dimensions

A dimension is a field that you group by. The response has one row for each unique combination of the values of the dimensions, and each row contains the value of each dimension. The measures in a row are calculated from only the data in that group. dimensions is equivalent to a SQL GROUP BY. More dimensions give more rows, and each row contains less data:

`dimensions`	Rows in the response
`[]`	1 row: the total.
`["connection_type"]`	1 row for each platform.
`["connection_type", "usage_type"]`	1 row for each service on each platform.
`["day", "connection_type"]`	1 row for each platform on each day.

A dimension that is not in dimensions does not split the rows. For example, ["connection_type"] with a 30-day filter gives the total of the 30 days for each platform, not a row for each day.

Time dimensions

To show a trend, add a time dimension to dimensions. The time dimension sets the size of each time bucket:

Dimension	Value in each row
`hour`	The start of the hour, as a timestamp with a UTC offset, for example `2026-09-01T14:00:00.000+0000`.
`day`	The date, for example `2026-09-01`.
`week`	The date of the Monday that starts the week.
`month`	The date of the first day of the month.
`quarter`	The date of the first day of the quarter.
`day_of_week`	The name of the day, for example `Mon`. Use it to compare days of the week.

All dates and hours are in UTC. Some rules apply to time buckets:

The first and last buckets can be partial. For example, a 30D range with week usually starts and stops in the middle of a week. The first and last rows then contain less data than the other rows.
Filter on day, and group by the larger bucket. To get monthly spend for the year, filter day with YTD and add month to dimensions. Do not filter on week, month or quarter.
Hour-level data comes from a different table. SELECT keeps spend in a daily table and in an hourly table. If your request uses hour, or another field that only the hourly table has, SELECT reads the hourly table. Otherwise, SELECT reads the daily table, which is faster. The totals are the same. You do not select the table.

Filters

filter_expression limits the rows that SELECT uses to calculate the measures. It is equivalent to a SQL WHERE. It is a tree: each node has an operator of and or or, and a list of filters. An item in filters can be a filter or another node. This request gets the spend on Snowflake compute or storage for the last 90 days:

{
  "measures": ["sum_spend"],
  "dimensions": ["usage_type"],
  "filter_expression": {
    "operator": "and",
    "filters": [
      {"field": "day", "operator": "in range", "value": "90D"},
      {"field": "connection_type", "operator": "=", "value": "Snowflake"},
      {
        "operator": "or",
        "filters": [
          {"field": "spend_category", "operator": "=", "value": "Compute"},
          {"field": "spend_category", "operator": "=", "value": "Storage"}
        ]
      }
    ]
  },
  "limit": 1000
}

Operators	Value
`=`, `!=`, `>`, `>=`, `<`, `<=`	`value`: one value.
`in`, `not in`	`values`: a list.
`is`, `is not`	No value. Compares to null.
`ilike`, `startswith`	`value` or `values`. `ilike` matches a part of the text and ignores case.
`in range`, `not in range`	`value`: a relative date range.
`array_contains`	`values`: a list. The array field must contain one of the values.

Date ranges

Filter dates on the day field. To use fixed dates, use two filters. Both bounds are inclusive:

[
  {"field": "day", "operator": ">=", "value": "2026-08-01"},
  {"field": "day", "operator": "<=", "value": "2026-08-31"}
]

To use a range relative to today, use one in range filter:

Value	Range
`30D`	The last 30 days, today included.
`3M`	The last 3 months, today included.
`WTD`, `MTD`, `QTD`, `YTD`	From the start of the current week, month, quarter or year, to today.
`LMTD`	All of the previous calendar month.

Text values are case-sensitive. A value with incorrect case matches no rows, and SELECT does not return an error. For example, on spend, connection_type is Snowflake, Bigquery or Databricks. The value snowflake matches no rows.

Measure filters

measure_filters removes groups after SELECT calculates the measures. It is equivalent to a SQL HAVING. Use it to remove small groups from the response. This request gets the warehouses that cost more than $1,000 last month:

{
  "measures": ["sum_spend"],
  "dimensions": ["warehouse_name"],
  "filter_expression": {
    "operator": "and",
    "filters": [
      {"field": "day", "operator": "in range", "value": "LMTD"},
      {"field": "connection_type", "operator": "=", "value": "Snowflake"}
    ]
  },
  "measure_filters": [{"field": "sum_spend", "operator": ">", "value": 1000}],
  "sort": [{"field": "sum_spend", "direction": "desc"}],
  "limit": 1000
}

A filter in filter_expression changes the value of each measure. A filter in measure_filters does not change a value. It only removes rows.

Usage groups

A usage group set divides your cost into named groups, for example departments or teams. You define usage group sets in the SELECT app, or with the /v2/usage-group-sets routes. A model that has a usage_group dimension can group or filter by the groups of your sets. To group by the groups of one set, give the name of the set in path:

{
  "measures": ["sum_spend"],
  "dimensions": [{"field": "usage_group", "path": ["Department"]}],
  "filter_expression": {
    "operator": "and",
    "filters": [{"field": "day", "operator": "in range", "value": "MTD"}]
  },
  "limit": 1000
}

path[0] is the name of the set, not its ID.
A usage_group dimension with no path groups by all your sets at the same time.
To get the cost of one group, use the same form in a filter: {"field": {"field": "usage_group", "path": ["Department"]}, "operator": "=", "value": "Engineering"}.
To test a set before you save it, send its definition in usage_group_sets. SELECT then uses that definition in place of your saved sets.

Sort and limit

sort is a list of fields and directions. The first item sorts first. You can sort by a dimension or a measure:

"sort": [{"field": "day", "direction": "asc"}, {"field": "sum_spend", "direction": "desc"}]

limit is the maximum number of rows in the response. The metrics routes do not paginate: page_token is always null. If a query has more rows than limit, SELECT removes the rows after the limit, and does not return an error. Always set a limit. To get the top N groups, sort by a measure and set limit to N.

Period over period

Some models have measures that compare a period to the period before it: <measure>_previous_period, change_<measure> and percent_change_<measure>. The previous period has the same number of days, and stops on the day before your range starts. For these measures, the request must have one day range at the top level of filter_expression. Use one in range filter, or one >= filter and one <= filter.

{
  "measures": ["sum_spend", "sum_spend_previous_period", "change_sum_spend", "percent_change_sum_spend"],
  "dimensions": ["connection_type"],
  "filter_expression": {
    "operator": "and",
    "filters": [{"field": "day", "operator": "in range", "value": "30D"}]
  },
  "limit": 1000
}

For QTD on 2026-09-28, the range is 2026-07-01 to 2026-09-28 (90 days). The previous period is the 90 days from 2026-04-02 to 2026-06-30. It is not the previous calendar quarter.

Listing rows

To get rows with no grouping, set aggregate to false, and send only dimensions. For example, on snowflake-queries, this gives the individual queries. If the request also has measures or measure_filters, SELECT groups the rows, and does not return an error. Always set a limit when you list rows.

Teams

To query as one of your teams, send the X-Team-Id header. The response then contains only the data that the roles of the team give access to. This header may not be functional on all routes, reach out to the SELECT team if needed.

Get Started

Endpoints

Overview

Your first query

Request body

Measures

Dimensions

Time dimensions

Filters

Date ranges

Measure filters

Usage groups

Sort and limit

Period over period

Listing rows

Teams

​Overview

​Your first query

​Request body

​Measures

​Dimensions

​Time dimensions

​Filters

​Date ranges

​Measure filters

​Usage groups

​Sort and limit

​Period over period

​Listing rows

​Teams

Overview

Your first query

Request body

Measures

Dimensions

Time dimensions

Filters

Date ranges

Measure filters

Usage groups

Sort and limit

Period over period

Listing rows

Teams