Query Costs API

The Query Costs API runs the same cost, usage, metric, formula, and budget series you build in Explorer. Call POST /queries/run from your own scripts, CI jobs, or internal tools with a bearer token from the API overview. This is the HTTP surface behind the Costory MCP query tool and the Explorer UI. A query that works in chat or in the app works here with the same request body.

What you can query

Each item in queries is a series. Every series needs a type and a single-letter name (a, b, c, …). Put human labels in alias, not in name.

`type`	Use for
`cost`	Cloud spend (`metricId`: `cost`, `contracted_cost`, `effective_cost`, …)
`usage`	Infra usage units (CPU hours, K8s waste, …)
`metric`	Saved business metrics from your datasources
`externalMetric`	Live Tsuga or BigQuery metrics
`formula`	Ratios and derived series (`a / b`, `a - b`)
`budget`	Budget burn against a budget version id

Scope vs split:

filterCel scopes which rows to include (for example EC2 only).
groupBy splits the result into series or rows (for example per environment).

Label dimensions use the cos_ prefix (cos_service_name, cos_environment). Untagged resources are CEL null (cos_environment == null).

A query in one call

Prefer a datePreset when one matches. Pass from and to only for custom ranges. Do not combine a preset with explicit dates.

curl -X POST https://app-api.costory.io/queries/run \
  -H "Authorization: Bearer <your-api-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "queries": [{
      "type": "cost",
      "name": "a",
      "alias": "AWS by service",
      "metricId": "cost",
      "currency": "USD",
      "groupBy": "cos_service_name",
      "filterCel": "cos_provider in [\"AWS\"]",
      "chartType": "BAR"
    }],
    "datePreset": "TRAILING_90_DAYS",
    "aggBy": "Period"
  }'

Period-over-period comparison uses the same endpoint. Add compare: {} (or { "enabled": true }) and Costory derives the preceding period from your preset:

{
  "queries": [{ "type": "cost", "name": "a", "metricId": "cost", "currency": "USD" }],
  "datePreset": "LAST_MONTH",
  "compare": {}
}

The response is either a time series (kind: series) or a comparison (kind: comparison) when compare is enabled.

Discover dimensions and metrics first

Before you invent CEL field names or metric ids, call the companion list endpoints:

List queryable dimensions for groupBy and filterCel fields
List business metrics for saved metric series ids
List usage metrics for usage series ids

Diff tree for cost changes

When you need a rollup tree of what moved between two periods (not a flat Explorer comparison), use Run a cost-change diff tree. It requires an enabled comparison, a non-hourly aggBy, and at least one groupBy on a single cost or usage series.

Endpoints

Use the pages in this section for the full schema and to try each call.

Last modified on August 10, 2026

Getting started

Reports API

Report Previews

Alerts V2

Dimensions

Metrics

Reports

Query Costs

Events

Admin

Admin Billing Datasources

Admin Metrics Datasources

Admin Teams

Query Costs API

What you can query

A query in one call

Discover dimensions and metrics first

Diff tree for cost changes

Endpoints

​What you can query

​A query in one call

​Discover dimensions and metrics first

​Diff tree for cost changes

​Endpoints

What you can query

A query in one call

Discover dimensions and metrics first

Diff tree for cost changes

Endpoints