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

# Query Costs API

> Run Costory Explorer cost queries over HTTP. Filter with CEL, group by dimensions, compare periods, and pull the same series the app and MCP use.

The Query Costs API runs the same cost, usage, metric, formula, and budget series you build in [Explorer](/features/cost-explorer). Call `POST /queries/run` from your own scripts, CI jobs, or internal tools with a bearer token from the [API overview](/api-reference/overview).

This is the HTTP surface behind the [Costory MCP](/features/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.

```bash theme={null}
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:

```json theme={null}
{
  "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](/api-reference/queries/list-queryable-dimensions) for `groupBy` and `filterCel` fields
* [List business metrics](/api-reference/queries/list-business-metrics) for saved `metric` series ids
* [List usage metrics](/api-reference/queries/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](/api-reference/queries/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.