# Archive a billing datasource
Source: https://docs.costory.io/api-reference/admin-billing-datasources/archive-a-billing-datasource

/api-reference/openapi.json delete /terraform/billingDatasources/{id}



# Create a billing datasource
Source: https://docs.costory.io/api-reference/admin-billing-datasources/create-a-billing-datasource

/api-reference/openapi.json post /terraform/billingDatasources



# Get a billing datasource
Source: https://docs.costory.io/api-reference/admin-billing-datasources/get-a-billing-datasource

/api-reference/openapi.json get /terraform/billingDatasources/{id}



# Validate billing datasource configuration
Source: https://docs.costory.io/api-reference/admin-billing-datasources/validate-billing-datasource-configuration

/api-reference/openapi.json post /terraform/billingDatasources/validate



# Archive a metrics datasource
Source: https://docs.costory.io/api-reference/admin-metrics-datasources/archive-a-metrics-datasource

/api-reference/openapi.json delete /terraform/metricsDatasources/{id}



# Create a metrics datasource
Source: https://docs.costory.io/api-reference/admin-metrics-datasources/create-a-metrics-datasource

/api-reference/openapi.json post /terraform/metricsDatasources



# Get a metrics datasource
Source: https://docs.costory.io/api-reference/admin-metrics-datasources/get-a-metrics-datasource

/api-reference/openapi.json get /terraform/metricsDatasources/{id}



# Update an AWS S3 v2 metrics datasource definition
Source: https://docs.costory.io/api-reference/admin-metrics-datasources/update-an-aws-s3-v2-metrics-datasource-definition

/api-reference/openapi.json patch /terraform/metricsDatasources/{id}



# Validate metrics datasource configuration
Source: https://docs.costory.io/api-reference/admin-metrics-datasources/validate-metrics-datasource-configuration

/api-reference/openapi.json post /terraform/metricsDatasources/validate



# Add a member to a team via Admin API
Source: https://docs.costory.io/api-reference/admin-teams/add-a-member-to-a-team-via-admin-api

/api-reference/openapi.json post /terraform/teams/{id}/members
The path parameter may be the team id or the team name (case-insensitive).



# Archive a team via Admin API
Source: https://docs.costory.io/api-reference/admin-teams/archive-a-team-via-admin-api

/api-reference/openapi.json delete /terraform/teams/{id}
The path parameter may be the team id or the team name (case-insensitive).



# Create a team via Admin API
Source: https://docs.costory.io/api-reference/admin-teams/create-a-team-via-admin-api

/api-reference/openapi.json post /terraform/teams



# Get a team via Admin API
Source: https://docs.costory.io/api-reference/admin-teams/get-a-team-via-admin-api

/api-reference/openapi.json get /terraform/teams/{id}
The path parameter may be the team id or the team name (case-insensitive). Returns full team detail including members (with user) and pending invites.



# List teams in the organization via Admin API
Source: https://docs.costory.io/api-reference/admin-teams/list-teams-in-the-organization-via-admin-api

/api-reference/openapi.json get /terraform/teams
Returns all non-archived teams for the authenticated organization (admin IAM — same list service as SPA `/teams`).



# Remove a member from a team via Admin API
Source: https://docs.costory.io/api-reference/admin-teams/remove-a-member-from-a-team-via-admin-api

/api-reference/openapi.json delete /terraform/teams/{id}/members/{userId}
The path parameter may be the team id or the team name (case-insensitive).



# Sync all members of a team via Admin API
Source: https://docs.costory.io/api-reference/admin-teams/sync-all-members-of-a-team-via-admin-api

/api-reference/openapi.json post /terraform/teams/{id}/SYNC
Replaces the full member list of a team. Existing members not in the payload are removed, new ones are added or invited. The path parameter may be the team id or the team name (case-insensitive).



# Update a team via Admin API
Source: https://docs.costory.io/api-reference/admin-teams/update-a-team-via-admin-api

/api-reference/openapi.json patch /terraform/teams/{id}
The path parameter may be the team id or the team name (case-insensitive).



# Get service account details
Source: https://docs.costory.io/api-reference/admin/get-service-account-details

/api-reference/openapi.json get /terraform
Returns service account information for the Admin API.



# Archive an alert
Source: https://docs.costory.io/api-reference/alerts-v2/archive-an-alert

/api-reference/openapi.json post /alerts-v2/{alertId}/archive



# Create a budget alert
Source: https://docs.costory.io/api-reference/alerts-v2/create-a-budget-alert

/api-reference/openapi.json post /alerts-v2/budgetAlerts
Creates an alert for budget lines visible to the caller. Threshold percentages are ordered from highest severity to lowest.



# Create a cost alert
Source: https://docs.costory.io/api-reference/alerts-v2/create-a-cost-alert

/api-reference/openapi.json post /alerts-v2/costAlerts
Creates either a condition-based alert (`condition` plus `dedup`) or a legacy threshold-based alert. The example monitors production AWS compute spend using Costory dimensions.



# Delete an archived alert
Source: https://docs.costory.io/api-reference/alerts-v2/delete-an-archived-alert

/api-reference/openapi.json delete /alerts-v2/{alertId}



# Get an alert template
Source: https://docs.costory.io/api-reference/alerts-v2/get-an-alert-template

/api-reference/openapi.json get /alerts-v2/templates/{templateId}



# Get budget alert destination options
Source: https://docs.costory.io/api-reference/alerts-v2/get-budget-alert-destination-options

/api-reference/openapi.json get /alerts-v2/budgetAlerts/configurationFormData



# Get cost alert destination options
Source: https://docs.costory.io/api-reference/alerts-v2/get-cost-alert-destination-options

/api-reference/openapi.json get /alerts-v2/costAlerts/configurationFormData



# Get cost alert editor data
Source: https://docs.costory.io/api-reference/alerts-v2/get-cost-alert-editor-data

/api-reference/openapi.json get /alerts-v2/costAlerts/{id}/edit



# Get cost alert firing history
Source: https://docs.costory.io/api-reference/alerts-v2/get-cost-alert-firing-history

/api-reference/openapi.json get /alerts-v2/costAlerts/{id}/history



# Get cost alert widget data
Source: https://docs.costory.io/api-reference/alerts-v2/get-cost-alert-widget-data

/api-reference/openapi.json get /alerts-v2/costAlerts/{id}/widgetData



# List alert templates
Source: https://docs.costory.io/api-reference/alerts-v2/list-alert-templates

/api-reference/openapi.json get /alerts-v2/templates



# List budgets eligible for alerts
Source: https://docs.costory.io/api-reference/alerts-v2/list-budgets-eligible-for-alerts

/api-reference/openapi.json get /alerts-v2/budgets-with-alert-status



# List cost alerts
Source: https://docs.costory.io/api-reference/alerts-v2/list-cost-alerts

/api-reference/openapi.json get /alerts-v2/costAlerts



# List cost and budget alerts
Source: https://docs.costory.io/api-reference/alerts-v2/list-cost-and-budget-alerts

/api-reference/openapi.json get /alerts-v2
Returns the current Alerts V2 table payload. This camelCase route is the supported application contract; canonical public resource naming is a separate follow-up.



# Restore an alert
Source: https://docs.costory.io/api-reference/alerts-v2/restore-an-alert

/api-reference/openapi.json post /alerts-v2/{alertId}/restore



# Send a budget alert test notification
Source: https://docs.costory.io/api-reference/alerts-v2/send-a-budget-alert-test-notification

/api-reference/openapi.json post /alerts-v2/budgetAlerts/sendTest



# Send a cost alert test notification
Source: https://docs.costory.io/api-reference/alerts-v2/send-a-cost-alert-test-notification

/api-reference/openapi.json post /alerts-v2/costAlerts/test



# Snooze an alert
Source: https://docs.costory.io/api-reference/alerts-v2/snooze-an-alert

/api-reference/openapi.json post /alerts-v2/{alertId}/snooze



# Unsnooze an alert
Source: https://docs.costory.io/api-reference/alerts-v2/unsnooze-an-alert

/api-reference/openapi.json post /alerts-v2/{alertId}/unsnooze



# Update a budget alert
Source: https://docs.costory.io/api-reference/alerts-v2/update-a-budget-alert

/api-reference/openapi.json put /alerts-v2/budgetAlerts/{budgetAlertId}



# Update a cost alert
Source: https://docs.costory.io/api-reference/alerts-v2/update-a-cost-alert

/api-reference/openapi.json put /alerts-v2/costAlerts/{id}



# Get published label transformations
Source: https://docs.costory.io/api-reference/dimensions/get-published-label-transformations

/api-reference/openapi.json get /dimensions/labels
The currently published label configuration: which source columns are merged into each engineered dimension and how their values are mapped. This is the live configuration, not a draft — the client holds label edits until it calls `POST /dimensions/publish`.



# List label keys that could become dimensions
Source: https://docs.costory.io/api-reference/dimensions/list-label-keys-that-could-become-dimensions

/api-reference/openapi.json get /dimensions/candidates
Label keys found in the billing data with the cost-allocation stats used to judge whether promoting them is worthwhile: the share of cost carrying the key, its values, a per-month cost series, and the month-over-month change. Property names are snake_case because they come straight from the billing export. `ingested: true` means the key is already promoted.



# List queryable dimensions
Source: https://docs.costory.io/api-reference/dimensions/list-queryable-dimensions

/api-reference/openapi.json get /dimensions
Returns every dimension available to filter and group by today, with its values and supported operators. Served from the cached dimension list refreshed by the compute pipeline, so a dimension published moments ago may not appear yet.



# Publish pending dimension changes
Source: https://docs.costory.io/api-reference/dimensions/publish-pending-dimension-changes

/api-reference/openapi.json post /dimensions/publish
Promotes pending dimension changes: the label configuration supplied inline in `labels`, and every pending virtual-dimension draft in the organization. `scope` narrows the publish to labels or virtual dimensions only.

Each draft is validated on its own and the valid set is promoted atomically. A `200` therefore does not mean everything was published: `unpublished[]` lists the drafts that failed validation, with per-draft error messages, while `publishedLabels` and `publishedVdimIds` report what did go live. A `400` means the request as a whole was rejected and nothing was promoted.

A successful publish enqueues an asynchronous BigQuery refresh (a full feature-engineering refresh when labels changed, a lighter update otherwise), so newly published dimensions are not immediately queryable.



# Search dimension values
Source: https://docs.costory.io/api-reference/dimensions/search-dimension-values

/api-reference/openapi.json get /dimensions/search
Full-text search across dimension names and their values. Unlike `GET /dimensions` this queries the billing warehouse live, so it is slower and costlier — use it for type-ahead, not to enumerate dimensions.



# Aggregate events
Source: https://docs.costory.io/api-reference/events/aggregate-events

/api-reference/openapi.json post /events/aggregate



# Create a new event
Source: https://docs.costory.io/api-reference/events/create-a-new-event

/api-reference/openapi.json post /public/events
Endpoint to create a new event using public API.



# Create a new event
Source: https://docs.costory.io/api-reference/events/create-a-new-event-1

/api-reference/openapi.json post /events
Endpoint to create a new event from the internal API.



# Delete an event
Source: https://docs.costory.io/api-reference/events/delete-an-event

/api-reference/openapi.json delete /events/{id}



# Get an event by ID
Source: https://docs.costory.io/api-reference/events/get-an-event-by-id

/api-reference/openapi.json get /events/{id}



# Get event tags
Source: https://docs.costory.io/api-reference/events/get-event-tags

/api-reference/openapi.json get /events/tags



# Update an event
Source: https://docs.costory.io/api-reference/events/update-an-event

/api-reference/openapi.json put /events/{id}



# List usage metrics
Source: https://docs.costory.io/api-reference/metrics/list-usage-metrics

/api-reference/openapi.json get /usage-metrics
Consumed units available for usage-based queries, with the services that report each unit.



# API overview
Source: https://docs.costory.io/api-reference/overview

Authenticate and call the Costory HTTP API. Use a bearer token from the Costory app for every request.

The Costory API exposes the same endpoints the app uses over HTTP. Base URL:

```bash theme={null}
https://app-api.costory.io
```

Start with the [Query Costs API](/api-reference/queries/overview) to run Explorer queries from your own tools, or the [Reports API](/api-reference/reports/overview) to create and schedule cost reports. To ingest hourly custom metrics, use [Custom Metrics Push](/setup/usage-metrics/custom-metrics-push) (`POST /integrations/:id/metrics/points` with an organization API key). More resources (Events, Teams, and others) are listed in this API Reference tab as they ship.

## Authentication

All requests use a bearer token in the `Authorization` header. Create a user-scoped token or an organization-scoped token (admins only) in the [Costory app](https://app.costory.io/).

```bash theme={null}
Authorization: Bearer <your-api-token>
```

<Frame>
  <img alt="Create a user scoped token in Costory settings" />
</Frame>


# List business metrics
Source: https://docs.costory.io/api-reference/queries/list-business-metrics

GET /queries/metrics
Business `metricId` values accepted by `metric` series, grouped by datasource. `status` is a stored value and is not refreshed on read for API-key callers.



# List queryable dimensions
Source: https://docs.costory.io/api-reference/queries/list-queryable-dimensions

GET /queries/dimensions
Group-by axes and their values accepted by `groupBy` on cost/usage/metric series. Strict public shape — no react-querybuilder filter-widget fields.



# List usage metrics
Source: https://docs.costory.io/api-reference/queries/list-usage-metrics

GET /queries/usage-metrics
Usage `metricId` values (and units) accepted by `usage` series.



# Query Costs API
Source: https://docs.costory.io/api-reference/queries/overview

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.


# Run a cost-change diff tree
Source: https://docs.costory.io/api-reference/queries/run-a-cost-change-diff-tree

POST /queries/diff-tree
Returns a `GROUP BY ROLLUP` tree of current vs previous cost per node for exactly one `cost` or `usage` series. Requires an enabled comparison period, a non-hourly `aggBy`, and at least one `groupBy` axis on that series. Pre-condition failures return `400 INVALID_QUERY` with today's message in `reason`. There is no Hour entitlement gate — hourly is rejected for every organization.



# Run a cost query
Source: https://docs.costory.io/api-reference/queries/run-a-cost-query

POST /queries/run
Executes a CEL query and returns either a time series (`kind: series`) or a period-over-period comparison (`kind: comparison`) when `compare.enabled` is true. Organization comes from the authenticated principal (Clerk session JWT or `ak_*` API key). When `datePreset` is sent alongside `from`/`to`, the preset wins. An omitted `limit` is server-chosen (currently between 10 and 200 depending on the chart shape), not a flat default of 100.



# List business metrics
Source: https://docs.costory.io/api-reference/query-costs/list-business-metrics

/api-reference/openapi.json get /queries/metrics
Business `metricId` values accepted by `metric` series, grouped by datasource. `status` is a stored value and is not refreshed on read for API-key callers.



# List queryable dimensions
Source: https://docs.costory.io/api-reference/query-costs/list-queryable-dimensions

/api-reference/openapi.json get /queries/dimensions
Group-by axes and their values accepted by `groupBy` on cost/usage/metric series. Strict public shape — no react-querybuilder filter-widget fields.



# List usage metrics
Source: https://docs.costory.io/api-reference/query-costs/list-usage-metrics

/api-reference/openapi.json get /queries/usage-metrics
Usage `metricId` values (and units) accepted by `usage` series.



# Run a cost-change diff tree
Source: https://docs.costory.io/api-reference/query-costs/run-a-cost-change-diff-tree

/api-reference/openapi.json post /queries/diff-tree
Returns a `GROUP BY ROLLUP` tree of current vs previous cost per node for exactly one `cost` or `usage` series. Requires an enabled comparison period, a non-hourly `aggBy`, and at least one `groupBy` axis on that series. Pre-condition failures return `400 INVALID_QUERY` with today's message in `reason`. There is no Hour entitlement gate — hourly is rejected for every organization.



# Run a cost query
Source: https://docs.costory.io/api-reference/query-costs/run-a-cost-query

/api-reference/openapi.json post /queries/run
Executes a CEL query and returns either a time series (`kind: series`) or a period-over-period comparison (`kind: comparison`) when `compare.enabled` is true. Organization comes from the authenticated principal (Clerk session JWT or `ak_*` API key). When `datePreset` is sent alongside `from`/`to`, the preset wins. An omitted `limit` is server-chosen (currently between 10 and 200 depending on the chart shape), not a flat default of 100.



# Archive a report
Source: https://docs.costory.io/api-reference/reports/archive-a-report

DELETE /reports/{id}
Soft-archives the report (sets `archivedAt`).



# Create a report
Source: https://docs.costory.io/api-reference/reports/create-a-report

POST /reports
Creates a report. Rules not captured by the field types: at least one `destinations` entry is required; when `scheduledPeriod` is `WEEKLY`, `scheduledWeekday` (0=Sunday…6=Saturday) is required; EMAIL destinations must be a valid address (or `ALL_ACTIVE_USERS`); and a DIGEST widget rendered as a `table` supports at most two group-by dimensions (report `context.groupBy` plus `additionalGroupBy`).



# Duplicate a report
Source: https://docs.costory.io/api-reference/reports/duplicate-a-report

POST /reports/{id}/duplicate



# Get a report
Source: https://docs.costory.io/api-reference/reports/get-a-report

GET /reports/{id}



# Get a report execution
Source: https://docs.costory.io/api-reference/reports/get-a-report-execution

/api-reference/openapi.json get /report-executions/{executionId}



# List reports
Source: https://docs.costory.io/api-reference/reports/list-reports

GET /reports
Returns reports visible to the authenticated user. Optional `recentExecutionsLimit` embeds recent execution rows per report.



# Reports API
Source: https://docs.costory.io/api-reference/reports/overview

Create, schedule, preview, and run Costory cost reports over HTTP. The same API powers scheduling from the UI and from chat via the Costory MCP.

The Reports API creates and schedules the cost reports described in [Cost Reports](/features/slack-reports). Every report you build in the UI or ask the [Costory MCP](/features/mcp) to create resolves to a call against these endpoints, so anything you can schedule by hand you can automate here.

Authenticate with a bearer token as described in the [API overview](/api-reference/overview).

## A report in one call

A report ties together a scope, one or more widgets, a cadence, and the channels it goes to. [Create a report](/api-reference/reports/create-a-report) accepts all of it in a single `POST /reports` body:

* `context` sets the shared scope, group-by, and period the widgets inherit.
* `widgets` holds the trend graph, the top and bottom ranking, or the Digest breakdown to render.
* `scheduledPeriod` and `scheduledWeekday` set the cadence (or `null` for an on-demand report you trigger yourself).
* `destinations` lists the Slack, Microsoft Teams, or email targets the report fans out to on every run.

Before scheduling, [preview a widget](/api-reference/reports/preview-a-report-widget) or [send a test delivery](/api-reference/reports/send-a-test-report) to check the format and data.

## Endpoints

Use the pages in this section to see the full schema and try each call against staging.


# Preview a report widget
Source: https://docs.costory.io/api-reference/reports/preview-a-report-widget

POST /report-previews/widgets



# Preview digest summary markdown
Source: https://docs.costory.io/api-reference/reports/preview-digest-summary-markdown

/api-reference/openapi.json post /report-previews/digest-summary



# Retry a failed report execution
Source: https://docs.costory.io/api-reference/reports/retry-a-failed-report-execution

/api-reference/openapi.json post /report-executions/{executionId}/retry



# Run a report now
Source: https://docs.costory.io/api-reference/reports/run-a-report-now

POST /reports/{reportId}/executions
Enqueues and synchronously runs pending executions for every destination.



# Send a test report
Source: https://docs.costory.io/api-reference/reports/send-a-test-report

POST /report-previews/deliveries



# Send a test report delivery
Source: https://docs.costory.io/api-reference/reports/send-a-test-report-delivery

/api-reference/openapi.json post /report-previews/deliveries



# Transfer a rendered execution to new destinations
Source: https://docs.costory.io/api-reference/reports/transfer-a-rendered-execution-to-new-destinations

/api-reference/openapi.json post /report-executions/{executionId}/transfers



# Update a report
Source: https://docs.costory.io/api-reference/reports/update-a-report

PATCH /reports/{id}
Partially updates a report; omitted fields are left unchanged. `widgets` and `destinations`, when provided, replace the existing lists wholesale. Same conditional rules as create apply: a WEEKLY cadence needs a `scheduledWeekday` (from this body or already stored), EMAIL destinations must be valid addresses, and a `table` DIGEST widget allows at most two group-by dimensions. Archived reports cannot be updated (409).



# Decentralize FinOps with Per-Team Cost Reports
Source: https://docs.costory.io/automate-reporting/decentralize-finops

Scale cost visibility across engineering teams by scoping automated reports to each squad. Deliver cloud cost insights via Slack, Teams, or email, no billing console access needed.

When FinOps sits with one person, every other team is blind to its own cloud spend. Cost-saving work is hard to track, teams can't see the impact of their changes, and the FinOps owner becomes a bottleneck.

This guide scopes automated cost reports to each team using Costory's [Slack, Teams, and email reports](/features/slack-reports), so every squad sees its own costs.

<iframe title="Embedded content" />

## Prerequisites

* Your cloud billing data is connected to Costory (see [Quickstart](/get-started/quickstart)).
* You have a way to scope costs per team, either via native cloud tags, via [dimensions](/features/tagging/dimensions) that map resources to teams, or via [Teams](/features/teams) with persistent cost scopes.

## What you get

* Per-team cost reports delivered automatically via Slack, Teams, or email.
* Each squad sees only the data relevant to them. No noise, no manual digging.
* A continuous feedback loop that keeps teams accountable for their cloud spend.

## How to decentralize FinOps step by step

<Steps>
  <Step title="Scope a view to a team">
    Open any view in [Explorer](/features/cost-explorer) and filter to the scope you want to report on: a specific team, service, or environment.

    Reports can be scoped using:

    * **CSP metadata:** cloud provider attributes like service name, region, or account
    * **Native labels:** your existing cloud resource tags
    * **Dimensions:** imported tags and rule-based mappings to teams, environments, features, or custom groupings via [Dimensions](/features/tagging/dimensions)

    <Frame>
      <img alt="Decentralize FinOps" />
    </Frame>
  </Step>

  <Step title="Schedule automated delivery">
    Create a scheduled report from your current view. Configure the delivery channel (Slack, Teams, or email) and set the cadence: weekly or monthly.

    Reports run automatically, giving teams a continuous feedback loop.

    <Frame>
      <img alt="Decentralize FinOps, schedule a report" />
    </Frame>

    For example: your backend team gets a weekly Slack report scoped to their services, your data team gets one scoped to BigQuery and Datadog, and leadership gets a monthly summary across everything.

    <Tip>
      You can set up each team's report from chat with the [Costory MCP](/features/mcp): "schedule a weekly Slack report of the backend team's costs to their channel."
    </Tip>
  </Step>

  <Step title="Iterate and expand coverage">
    Start with one or two teams, validate the report content, then roll out to all squads. Combine with [budgets](/use-cases/automate_budget) to add spending alerts alongside the reports.
  </Step>
</Steps>

## Next steps

* **Add event context to team reports:** Connect [events](/setup/events) so each team sees deploys and incidents alongside their costs. See [Event Correlations](/automate-reporting/event-correlation).
* **Include unit economics:** Show teams their cost per user or per request, not just total spend. See [Relate Costs to Usage](/automate-reporting/unit-economics).
* **Automate the monthly review:** Use the [Digest](/features/digest) for AI-generated org-wide reports. See [Monthly Cloud Cost Reporting](/automate-reporting/monthly-reviews).


# Event Correlations
Source: https://docs.costory.io/automate-reporting/event-correlation

Connect cost spikes to the events that caused them

When cloud costs spike, the cause is often known (a deployment, a new region, Black Friday) but nothing links that event to the cost data. Costory ingests technical and business events and aligns them with your cost timeline, so the link is recorded.

<iframe title="Embedded content" />

<img alt="Event Correlation" />

## Supported Inputs

<CardGroup>
  <Card title="AWS Commercial Events" icon="aws">
    Savings Plans, Reserved Instances, EDP renewals
  </Card>

  <Card title="GitHub Metadata" icon="github">
    PRs, deploys, labels, and release tags
  </Card>

  <Card title="CI/CD Pipelines" icon="gear">
    Custom events via API integration
  </Card>

  <Card title="Manual Events" icon="calendar-plus">
    Traffic spikes, client onboarding, campaigns
  </Card>
</CardGroup>

<img alt="Event Correlation" />

<Tip>
  All events are timestamped and visualized alongside cost time series. They also improve the accuracy of Digest summaries and ML-driven anomaly detection.
</Tip>

<img alt="Event Correlation" />

## Benefits

<CardGroup>
  <Card title="Faster Root Cause Analysis" icon="bolt">
    Event-aware timelines speed up investigations
  </Card>

  <Card title="Institutional Memory" icon="brain">
    Build shared context across engineering and finance
  </Card>

  <Card title="Better Explanations" icon="comment-dots">
    Improve accuracy of cost change narratives
  </Card>

  <Card title="Confident Anomaly RCA" icon="shield-check">
    Increase confidence in anomaly root cause analysis
  </Card>
</CardGroup>

## Next Steps

<Tip>
  You can log a one-off event from chat with the [Costory MCP](/features/mcp): "create an event called 'checkout v2 deploy' dated today" so the next cost shift lines up against it.
</Tip>

<CardGroup>
  <Card title="Connect Events" icon="link" href="/setup/events">
    Set up your event sources in Costory.
  </Card>

  <Card title="Monthly Reviews" icon="calendar" href="/automate-reporting/monthly-reviews">
    Use event context in automated reports.
  </Card>
</CardGroup>


# Automate Monthly Cloud Cost Reporting
Source: https://docs.costory.io/automate-reporting/monthly-reviews

Stop spending hours building monthly cloud cost reports. Use a Cost digest inside Costory Reports to generate executive summaries, root-cause analyses, and shareable Slack or email digests.

Reporting on last month's cloud invoice answers the same three questions every time: what happened, why did costs go up, and where are the anomalies. The format changes (Notion, PowerPoint, Slack) but the work does not.

It usually falls to a senior SRE or infrastructure lead and pulls them off engineering work. Costory cuts that monthly report from half a day to minutes.

This guide automates monthly <Tooltip href="/docs/glossary#finops-reporting">cloud cost reporting</Tooltip> with a [Cost digest](/features/digest) inside [Cost Reports](/v2/Automate/reports).

<iframe title="Monthly cost reporting with Cost digest" />

## Prerequisites

* Your cloud billing data is connected to Costory (see [Quickstart](/get-started/quickstart)).
* Optionally, [events](/setup/events) (deploys, incidents, provider changes) are connected so the AI can reference them in its explanations.

## What you get

* A scheduled Cost Report whose body includes a **Cost digest** tree of the biggest movers.
* AI-generated explanations for significant changes when **Enable AI investigation** is on.
* Delivery to Slack or email, plus Summary, Tree, and Table views in the Costory UI.

## How to automate monthly cost reporting step by step

<Steps>
  <Step title="Create a monthly Cost Report">
    Open [Reports](/v2/Automate/reports), create a report, and set parameters for the month you care about. Typical setup: **Metric** = Cost, **Group By** = Provider, comparison = last full month.

    <Frame>
      <img alt="Costory report builder for a monthly Cost digest" />
    </Frame>
  </Step>

  <Step title="Add a Cost digest element">
    Click **+ Add Element**, choose **Cost digest**, then add dimensions such as Environment and Service Name. Turn on **Enable AI investigation** so leaf nodes get root-cause text after delivery. Details: [Digest](/features/digest).

    <Frame>
      <img alt="Cost digest configuration for a monthly review" />
    </Frame>
  </Step>

  <Step title="Schedule Slack or email delivery">
    Set the report to monthly, add finance or leadership destinations, and save. Recipients get the Summary narrative. You can reopen the run in Costory and switch to Tree or Table for drill-down.

    <Frame>
      <img alt="Monthly Schedule and send settings for a Cost digest report" />
    </Frame>

    <Tip>
      To put this on autopilot from chat, ask the [Costory MCP](/features/mcp) to "schedule a monthly cost digest to my leadership channel on the first Tuesday of each month."
    </Tip>
  </Step>
</Steps>

## Next steps

* **Add context to your reports**: Connect [events](/setup/events) (deploys, incidents, provider changes) so Costory AI can reference them in its explanations.
* **Relate costs to usage**: Connect [external metrics](/setup/usage-metrics) to show that cost increases track with business growth. See [Relate Costs to Usage](/automate-reporting/unit-economics).
* **Share per-team reports**: Scope a digest with dimension filters and send each squad their own channel. See [Decentralize FinOps](/automate-reporting/decentralize-finops).


# Track Unit Economics to Justify Cloud Cost Increases
Source: https://docs.costory.io/automate-reporting/unit-economics

Link cloud cost increases to business growth by connecting external metrics in Costory and building unit economics formulas. Defend scaling decisions with data.

Not every cost increase is a problem. More customers, higher traffic, and new workloads all raise cloud spend. That nuance is usually lost when finance reviews the bill.

Engineering needs to show that costs grew because the business grew, not because something broke.

Connect a usage source from **Integrations** > **+ Add integration** > **External metric**, then define formulas in Explorer to track <Tooltip href="/docs/glossary#unit-economics">unit economics</Tooltip> over time.

<iframe title="Embedded content" />

## Prerequisites

* Your cloud billing data is connected to Costory (see [Quickstart](/get-started/quickstart)).
* You have access to a business or usage metric (for example active users, API calls, or transactions) from a source on the [External metric](/setup/usage-metrics) grid: Datadog, Datadog CI Visibility, Amplitude, BigQuery, Google Sheets, Tsuga, CloudWatch, or S3.

## What you get

* Usage metrics queried next to your cloud cost data.
* Custom unit economics formulas (cost per user, cost per request, cost per transaction, etc.) visualized over time.
* Evidence that cost increases track with business growth, ready to share with finance and leadership.

## How to track unit economics step by step

<Steps>
  <Step title="Connect a usage metric">
    Connect the usage data that matters to your business from any source on the [External metric](/setup/usage-metrics) grid: Datadog, Datadog CI Visibility, Amplitude, BigQuery, Google Sheets, Tsuga, CloudWatch, or S3.

    See [Metrics Correlation](/setup/usage-metrics) for connection details.

    <Frame>
      <img alt="Unit Economics" />
    </Frame>
  </Step>

  <Step title="Define a unit economics formula">
    Once you can query the metric in Advanced Explorer, define a formula in [Explorer](/features/cost-explorer) to track the KPIs that matter:

    * Cost per active customer, to track infrastructure efficiency per user
    * Storage cost per document, to monitor storage efficiency at the resource level
    * Lambda cost per OCR job, to measure serverless cost per operation
    * A custom KPI that matches how your business measures output

    These metrics can be visualized over time and scoped by team, product, or region.

    <Tip>
      The [Costory MCP](/features/mcp) can assemble the view for you: "build a cost-per-active-customer chart over the last 6 months and save it to a dashboard."
    </Tip>
  </Step>

  <Step title="Share unit economics with stakeholders">
    Use the resulting charts to show finance that your cost per user is going *down* even as total spend goes up.

    * Include unit economics in your [monthly cost report](/automate-reporting/monthly-reviews). The Digest can reference usage metrics in its AI-generated explanations.
    * Share per-team unit economics via [Cost Reports](/features/slack-reports).
    * Present the right metrics to leadership. See [FinOps metrics for exec team](/use-cases/what_your_exec_team_wants/value).
  </Step>
</Steps>

## Next steps

* **See a full example:** [Calculate your cost per thousand active users using Amplitude](/use-cases/amplitude/cost_per_active_users)
* **Show leadership the right numbers:** [FinOps metrics for exec team](/use-cases/what_your_exec_team_wants/value)
* **Share per-team reports:** Give each squad visibility into their own costs. See [Decentralize FinOps](/automate-reporting/decentralize-finops).


# Changelog
Source: https://docs.costory.io/changelog

Product updates and announcements

<Update label="September 8 2026">
  ### See Claude.ai and OpenAI spend in Explorer

  You can now see [claude.ai](https://claude.ai) Enterprise costs next to Claude Console API usage and the rest of your billing data. Connect **Anthropic Claude AI** under **Integrations**. You need an Enterprise subscription and a primary-owner Analytics API key.

  See [Anthropic billing](/setup/billing/anthropic).

  OpenAI Platform API usage lands in Explorer the same way. Costory takes the organization bill and reallocates it by usage onto each user, so you can isolate one person or one project from the same invoice.

  Two views this enables:

  * Spend for one user, grouped by **Resource name**
  * Spend for one OpenAI project, grouped by **Sub account id**

  Grant **API keys + Projects** read on the Admin key so those fields show names instead of ids.

  See [OpenAI billing](/setup/billing/openai).

  ### Chart cost per order from metrics you already emit

  You can now POST hourly metrics into Costory and use them like any other external series. That is enough to chart [unit economics](/features/unit-economics) such as cost per order, or to drive [shared cost allocation](/features/tagging/shared-cost-allocation) from a usage key you already emit.

  Create a **Custom metrics** integration, then send preaggregated hourly points. After the first push, click **Refresh metrics** so names appear in **Advanced Explorer**, [Costory MCP](/features/mcp), and [virtual dimensions](/features/tagging/dimensions#virtual-dimensions).

  If you run Prometheus, add an hourly or daily job that maps name, timestamp, labels, and value onto the POST. Costory does not pull remote-write.

  See [Custom Metrics Push](/setup/usage-metrics/custom-metrics-push).

  ### Forecast the rest of the month, quarter, or year

  Pick **Current Month**, **Current Quarter**, or **Current Year** in Explorer to see actuals plus a forecast for the rest of that period. Group by **Service name** or **SKU description** so each line gets its own forecast. A meaningful group-by is what makes the projection usable.

  ### Reuse a where clause across Explorer, dashboards, and alerts

  Copy a where clause from any builder and paste it into Explorer, a dashboard, or an alert. The same filter travels with you instead of being rewritten in each place.
</Update>

<Update label="September 1 2026">
  ### Google Cloud Monitoring metrics

  Connect Cloud Monitoring under **Integrations**, then query any active GCP metric in **Advanced Explorer**. Same path as CloudWatch, Datadog, and Tsuga.

  Two allocations this unlocks:

  * Network traffic as the key for shared networking cost
  * Cloud SQL cost from execution time, split by user and database

  See [GCP Cloud Monitoring](/setup/usage-metrics/gcp-cloud-monitoring).

  ### GCP spend-based commitments dashboard

  The **GCP Spend Based Commitments** template shows reservations and commitments by team, unused commitments, and unused reservations.

  Open it from [Dashboards](https://app.costory.io/dashboards/cmtin9lip004920ofsv2647ng).

  ### Alert on new charge descriptions

  A new SKU or marketplace charge is easy to miss until the invoice lands. Create an alert from the **New charge description** template and Costory flags the first time that description shows up.

  Start from the [New charge description template](https://app.costory.io/alerts-v2/costAlerts/new?templateId=never-seen-sku).

  ### Owners and tags on list views

  You can set **Owner** (user or team) and **Tags** from every list view in Costory.
</Update>

<Update label="August 25 2026">
  ### Scaleway and Cloudflare billing

  Import Scaleway consumption and Cloudflare PayGo usage from **Integrations** > **+ Add integration**, then analyze it with the rest of your billing data.

  Scaleway uses an IAM **secret key** with **BillingReadOnly** at Organization scope, plus the **Organization ID**. Cloudflare uses an API token with **Account / Billing / Read**, plus the **Account ID**. Cloudflare is PayGo and self-serve only. Enterprise contract billing is not on the public usage API.

  See [Scaleway billing](/setup/billing/scaleway) and [Cloudflare billing](/setup/billing/cloudflare).

  ### Snowflake tables as external metrics

  Business metrics such as active users, sessions, or devices often live in Snowflake while cost lives in Costory. If billing is already connected, grant the same Costory role a second database and query those tables in **Advanced Explorer**. Use the same path for technical signals in shared-cost allocation.

  See [Snowflake Metrics](/setup/usage-metrics/snowflake).

  ### Table widget display options

  Table widgets now expose a **Display** menu for how the grid is shown, without changing the query. Open **Display** on a table to sort rows, hide empty ones, cap the list with **Top N**, toggle a **Total** column, and set decimal **Precision**.

  <Frame>
    <img alt="Table widget Display menu with sort, hide empty rows, Top N, show total, and precision options" />
  </Frame>

  See [Dashboard widgets and chart types](/features/dashboards/widgets).
</Update>

<Update label="August 10 2026">
  ### Query Costs API

  You can now run Explorer queries over the public HTTP API. Authenticate with a bearer token and call `POST /queries/run` with the same series body the app and [Costory MCP](/features/mcp) use: cost, usage, metrics, formulas, budgets, CEL filters, group-bys, date presets, and period comparison.

  Companion endpoints list the dimensions and metric ids your queries can reference. A diff-tree endpoint returns a rollup of what moved between two periods.

  See the [Query Costs API](/api-reference/queries/overview) to get started.
</Update>

<Update label="July 20 2026">
  ### Costory MCP and skills, now inside the app

  Since mid July, almost half of our customers use Costory through the [Costory MCP](/features/mcp). We also know what holds the other half back: adding a new MCP server to Claude raises fair questions about token overhead and setup effort.

  So we brought the MCP into the app. The same tools and skills now power a chat directly in Costory:

  * New customers can try the MCP capabilities without installing anything.
  * When the app is not the best fit for a task, such as a complex analysis or a topic where you do not know where to start, the chat picks it up. This lets us ship smarter features without building a new screen for each one.

  <Frame>
    <img alt="Costory MCP and skills, now inside the app" />
  </Frame>

  We also cleaned up the tools themselves. Over time the catalog drifted from the original 10 tools to more than 30, so we simplified the schemas and now reuse the same schema across similar tools. Your MCP client loads fewer tokens for the same capabilities.

  Finally, the [costory-plugin repository](https://github.com/costory-io/costory-plugin) has new FinOps skills and more examples of what you can do with the Costory FinOps MCP.

  ### API first

  Every endpoint the app queries is now available as a public API, authenticated with a Clerk user or organization token. Available today:

  * [Query Costs](/api-reference/queries/overview)
  * [Reports](/api-reference/reports/overview)
  * [Events](/api-reference/events/create-a-new-event)
  * [Teams](/api-reference/admin-teams/list-teams-in-the-organization-via-admin-api)

  Next up:

  * Virtual Dimensions
  * Dimensions
  * Alerts
  * Budgets

  See the [API overview](/api-reference/overview) to get started.
</Update>

<Update label="July 6 2026">
  FinOps breaks when billing lives in one tool and the signal that explains it lives in another.... This week we focused on simplifying those integrations !

  ### Tsuga Connector:

  You can now connect Costory to your Tsuga infrastructure to:

  * Ingest Tsuga costs: get detailed cost breakdowns per API key, service and environment for your Tsuga fees.
  * Pull metrics from Tsuga to Costory to reallocate shared costs based on an external metric (e.g., cost per team for a shared API, cost per user for a shared database).
  * Pull metrics from Tsuga to Costory to calculate marginal cost.
  * Let our AI investigation agent investigate a cost change by searching and querying Tsuga metrics.

  > **What is [Tsuga](https://tsuga.com)?** Tsuga is an observability platform that runs on your cloud infrastructure, providing trace, APM, logging, and infrastructure monitoring.

  <Frame>
    <iframe title="Tsuga integration walkthrough" />
  </Frame>

  See the [Tsuga Connector](/setup/usage-metrics/tsuga) for more details.

  Test it out:

  ```
   Using Costory MCP, create a dashboard for S3 bucket analyses (resource_id analyses) daily trend last 45 days, find interesting cost drivers,        
  and a reallocated-cost widget using Tsuga monitoring_events — (events by api_key_id / total events) * bucket cost, formula (b/c)*a.    
  ```

  ### Query easily your BigQuery dataset for external metrics:

  We simplified the process to set up BigQuery Metrics: you no longer need to create a data source per table. Create an integration once per project, then access any table in the project directly from **Advanced Explorer**.

  This will also allow our AI investigation agent to investigate a cost change by searching and querying BigQuery metrics easily !

  <Frame>
    <iframe title="BigQuery external metrics and Costory integration demo" />
  </Frame>

  See the [BigQuery Metrics setup guide](/setup/usage-metrics/bigquery) for more details.

  ### Additional Changes:

  <Frame>
    <img alt="Undo redo in explorer and dashboards" />
  </Frame>

  * Explorer and dashboards: Both now keep a history of their last 50 states, so you can revert filters, charts, and layout without starting over. Full Dashboard Versioning is in progress and coming soon.
  * With the increased number of tools, tool description were no longer a good place to describe the tool and the workflow using it: We added a new tool `get_skill` in the MCP explaining the workflows we advise to use with our MCP:
    * Virtual Dimension Skill: two workflow options to create a virtual dimension.
    * Dashboard Skill: how to create an impactful dashboard.

  See the [FinOps MCP](/features/mcp) for setup and the full tool reference.
</Update>

<Update label="June 29 2026">
  ## Cloud cost allocation and alerts in the FinOps MCP

  ### Build virtual dimensions from your MCP client

  Many FinOps frameworks have a concept of <Tooltip href="/docs/glossary#virtual-dimensions">virtual dimension</Tooltip>, but writing the rules was never the hard part. The hard part is discovery: which field separates your spend, what values exist, and where they currently land. Until now that meant digging through Explorer first, then coming back to encode the rules separately. We moved that discovery loop into the MCP so it happens in one session.

  The [Costory FinOps MCP](/features/mcp) now exposes a set of tools built to streamline the discovery loop, so you can explore and define an allocation in one chat:

  * **Find interesting dimensions**: semantic search over your actual data. Query "ML" to surface every related dimension value, including LLM and ML-adjacent service names you wouldn't catch on a literal string match.
  * **Suggest additional split dimensions**: for a given service, returns candidate fields to split on, each ranked by how much of the spend it explains. Useful when you don't know the right dimension up front.
  * **Draft virtual dimension**: creates a draft from your rules and returns a preview of the resulting allocation over the past 30 days, before anything is published.
  * **Rule overlap matrix**: rule order is significant, and reordering can silently change what each rule catches. This returns a matrix of cost overlap between rules so you can verify ordering deterministically.

  When the split is right, the assistant saves it as a virtual dimension draft and publishes only on your approval. Edits stay on the draft, so production is unchanged until you confirm. On publish, Costory reprocesses your history and the dimension appears across Explorer, dashboards, alerts, and reports. See [Dimensions](/features/tagging/dimensions#explore-and-build-allocation-with-your-ai-assistant) for the full workflow.

  <Frame>
    <img alt="Costory MCP virtual dimension draft with ordered environment rules and allocation preview" />
  </Frame>

  **Try it** once your [MCP is set up](/features/mcp#add-costory-mcp-to-your-cursor-claude-dust):

  ```text theme={null}
  Using Costory MCP, I want to build a virtual dimension for my environment costs: Prod, R&D, Shared. Suggest me a split.
  ```

  ### Alerts v3: Formula-Based Alerting

  <Frame>
    <iframe title="Alerts v3: formula-based alerting walkthrough" />
  </Frame>

  When exposing Costory to LLMs via the Model Context Protocol (MCP), we hit an architectural wall: our legacy alert forms relied heavily on implicit UI state. To support LLMs, we needed to rebuild the alerting backend around explicit formulas.

  We rebuilt alerting around explicit formulas so both users and AI agents can see exactly how each alert is evaluated. Alerts v3 is a pure, formula-based engine built on top of our Advanced Explorer, bringing absolute predictability and rock-solid historical backtesting to cost alerting.

  <Frame>
    <img alt="Costory alerts page listing active cost alerts" />
  </Frame>

  You can now:

  * **Backtest alerts** against historical data before enabling them.
  * **Use formulas** for absolute cost, relative changes, week-over-week changes, and rolling windows.
  * **Create grouped alerts** by adding a `groupBy` to the base query, so one alert can evaluate every team, project, service, or environment independently.
  * **Reduce noise** by batching fired groups into one consolidated notification.

  | Operator                | Description                                    |
  | ----------------------- | ---------------------------------------------- |
  | `timeShift(a, 7, DAY)`  | Move the metric forward or backward in time    |
  | `rollingSum(a, 7, DAY)` | Rolling sum of the metric over the last 7 days |
  | `weekToDateSum(a)`      | Sum of the metric over the current week        |
  | `monthToDateSum(a)`     | Sum of the metric over the current month       |

  **Try it** from the [alert template in the app](https://app.costory.io/alerts-v2/costAlerts/new?templateId=service-7d-cost-increase), or from your MCP client:

  ```text theme={null}
  Create an alert on the 7-day relative change of my Claude costs. Only notify me if the absolute change is above $1000 and the relative change is above 10%.
  ```

  ### Additional Changes:

  We now support ClickHouse Cloud billing data [ClickHouse Billing Setup](/setup/billing/clickhouse): the integration allows to ingest Compute, Networking and Storage costs.
</Update>

<Update label="June 20 2026">
  ## Organize dashboards with tags

  You can now add tags to dashboards and bulk edit them from the **View all dashboards** page, making it easier to group dashboards by team, workflow, or FinOps process.

  <Frame>
    <img alt="Dashboard tags on the View all dashboards page" />
  </Frame>

  ## Customize chart color palettes

  You can now choose the color palette for each chart from four options, so dashboard visuals stay readable and consistent with the story you want to tell.

  <Frame>
    <img alt="Chart color palette options in a dashboard" />
  </Frame>
</Update>

<Update label="June 1 2026">
  ## BigQuery data exports (Copilot Pro)

  Query the same cost data you see in Costory from your own BigQuery project—use it in Looker, notebooks, or custom SQL without re-building filters by hand.

  On any [dashboard](/features/dashboards) widget, click **Copy SQL query** to copy the SQL for that view. An **Organization Admin** must grant your service account or user read access to the export table under **Integrations > Destinations**.

  <Frame>
    <img alt="Copy SQL query action on a dashboard widget" />
  </Frame>
</Update>

<Update label="May 19 2026">
  ## Costory v3: a simpler way to investigate cloud costs

  Two years ago, we built Costory to help you understand and manage cloud costs. Since then, we’ve spoken with many of you about how you use the platform every day.

  One theme came up often: the product had accumulated too many ways to do the same things.

  At the same time, LLMs are changing how teams work with their tools. Costory v3 is designed to help you move faster: investigate cost changes, capture context, and turn those investigations into reusable workflows through MCP, APIs, reports, and alerts.

  So we rebuilt the Costory experience around six core areas you rely on most.

  * **Explorer**: Your entrypoint for investigating cost changes.
  * **Dashboards**: Save investigations, revisit them later, and annotate them with events.
  * **Dimensions**: Standardize and group cost labels so every team can understand its costs.
  * **Events**: Add context to cost changes and connect events directly to your analysis.
  * **Reports**: Manage scheduled reports, scheduled dashboards, and cost digest analysis in one place. (Cost digests are coming later this month).
  * **Alerts**: Catch unexpected cost increases using fixed thresholds and relative thresholds.

  The search was also improved to help you explore faster: dashboards, dimensions, events and reports.
  For existing users, the transition is already complete. We migrated your views and redirected your existing URLs to the new layout.
  Tell us what still feels harder than before so we can improve it.
</Update>

<Update label="May 6 2026">
  ## Snowflake billing

  We now support **Snowflake** account usage and billing data in Costory. Create a **Snowflake** integration on **Integrations** with key-pair authentication, then add a **Snowflake** billing datasource that reuses that integration. **Terraform** is not available for this datasource yet (connect via the Costory UI).

  See the [Snowflake billing setup guide](/setup/billing/snowflake).
</Update>

<Update label="April 10 2026">
  ## Plot Budgets Alongside Actual Cost in the Explorer

  <img alt="Budget plotted alongside actual cost in Explorer" />

  You can now plot [budgets](/features/budgets) as an area chart directly in [Explorer](/features/cost-explorer). Open the metric selector, switch to the **budget** tab, and pick any budget to visualize its monthly target as a shaded area alongside your actual cost data.

  Use it to spot budget overruns as they happen: overlay your team's monthly budget on top of cumulated daily spend to see whether you're on track mid-month, or compare budget lines across squads to identify which teams are consistently over or under target. Click **Add related cost** to automatically add a cost series scoped to the budget's definition, with filters and group-by pre-filled so actual spend aligns with budget lines.
</Update>

<Update label="April 10 2026">
  ## Period-over-Period Cost Alerts

  <img alt="Alert threshold mode selector" />

  [Cloud cost alerts](/features/alerts) now support **relative thresholds** alongside absolute caps. Instead of only firing when spend crosses a fixed amount, you can configure alerts that trigger when costs **increase or decrease by more than a set amount or percentage** compared to the previous day, week, or month.

  Each threshold row has its own mode, so you can mix absolute and relative rules on the same alert. For example, get an informational notification when weekly spend increases by more than 10%, and escalate to a warning if it exceeds a hard dollar cap.

  Four threshold modes are available: **is above**, **is under**, **increases by more than**, and **decreases by more than**. For the relative modes, choose between an absolute delta (USD) or percentage change.
</Update>

<Update label="April 9 2026">
  ## New Billing Datasource

  You can now import Elastic Cloud organization billing and instance costs to Costory using an Organization API key and Organization ID. Data is normalized into <Tooltip href="/docs/glossary#standard-columns">Standard Columns</Tooltip> so you can explore Elastic spend next to AWS, GCP, Azure, and other [billing datasources](/setup/billing).

  See the new [Elastic Cloud billing setup guide](/setup/billing/elastic-cloud) for step-by-step instructions.
</Update>

<Update label="April 1 2026">
  ## New Metrics Datasource

  You can now import custom usage metrics directly from **AWS CloudWatch** into Costory. Create an AWS CloudWatch integration, paste your CloudWatch Insights query (for example S3 `BucketSizeBytes`, HTTP request counts, CPU utilization, or SQS queue depth), and Costory will keep these metrics in sync alongside your billing data. This makes it easier to build unit economics like cost per request, cost per active user, or cost per GB stored using real infrastructure signals.

  See the new [AWS CloudWatch usage metrics setup guide](/setup/usage-metrics/aws-cloudwatch) for step-by-step instructions and example queries.

  ## Small improvements

  * Teams Usage public API endpoints are now available: see in [https://app-api.costory.io/docs/](https://app-api.costory.io/docs/)
</Update>

<Update label="March 16 2026">
  ## Small improvements

  * You can set up billing data sources for AWS, Azure, GCP, Cursor, Anthropic, and more using a fully Terraform-based workflow. See [Billing Data](/setup/billing).
  * The MCP experience is improved: see [AI Assistant (MCP)](/features/mcp).

  The Costory team is at KubeCon this week; the next release is planned for April 1.
</Update>

<Update label="March 9 2026">
  ## Teams

  A single cost view rarely works for an entire organization. Your backend squad needs <Tooltip href="/docs/glossary#savings-plans">Contracted Cost</Tooltip> scoped to their services, while finance needs Billed Cost across everything. **Teams** let you configure those defaults once so each group lands on the right numbers without manual filtering. Learn more in [Teams](/features/teams).

  ## MCP (beta)

  The MCP server is in beta. Read [AI Assistant (MCP)](/features/mcp) and send feedback or suggestions to help shape what ships next.
</Update>

<Update label="March 2 2026">
  ## Small improvements

  * When a virtual dimension finishes computing and appears in the explorer, you get a notification in the top-right corner. The same applies to other long-running tasks in Costory.
  * Track [Cursor](https://www.cursor.com/) and Anthropic Claude Code spend: use [Cursor Billing Setup](/setup/billing/cursor) and [Anthropic Billing Setup](/setup/billing/anthropic).
</Update>

<Update label="Feb 24 2026">
  ## Events Page

  <img alt="Events page" />

  Track deployments, incidents, and infrastructure changes in a dedicated [Events page](/features/events) with full filtering and tagging support.

  * Browse all events with metadata, tags, and provider information at a glance
  * Inline explorer modal lets you see the cost impact of any single event without leaving the page
  * **Save as Context**: jump directly from an event into Explorer with filters pre-filled, so you can immediately drill into the cost impact

  ## Budget Configuration

  <img alt="Budget filling options" />

  New filling options make it easier to [configure budgets](/use-cases/automate_budget). Set monthly allocations manually, distribute evenly across the year, or use historical spend as a baseline — then adjust from there.
</Update>

<Update label="Feb 19 2026">
  ## Sharing & Collaboration

  <img alt="Explorer view sharing" />

  Share your analysis more easily than ever:

  * **Image sharing**: export any Explorer view as an image to share with your team
  * **[Slack previews](/features/slack-reports)**: shared views now render a rich preview directly in Slack, so recipients get context before clicking through
  * **Public share pages**: generate a shareable link for any view, accessible without logging in

  ## Dashboard Widget Duplication

  Duplicate any widget on a dashboard with a single click. The copy inherits all configuration — filters, groupings, and layout — so you can quickly create variations without starting from scratch.
</Update>

<Update label="Feb 12 2026">
  ## Templated Dashboards

  <img alt="Dashboard templates" />

  Get started faster with pre-built dashboard templates.

  Instead of building from scratch, pick a template that matches your use case and customize from there — widgets, filters, and layouts are all pre-configured and fully editable.

  ## Reports from Explorer

  <img alt="New Reports UI" />

  You can now [schedule reports](/features/slack-reports) directly from [Explorer](/features/cost-explorer).
  Build a visualization with custom aggregations, formulas, and comparisons, then set it to deliver automatically on your preferred cadence.

  We also introduced a new Reports tab inside the library, letting you find all your scheduled email and slack reports alongside existing views and dashboards.
</Update>

<Update label="Feb 9 2026">
  ## Dimensions

  Consolidate scattered cost labels into clean, standardized dimensions with the [Dimensions](/features/tagging/dimensions) page:

  <img alt="Dimensions label inspector" />

  * Merge columns from multiple sources into a single logical label
  * Map and rename values to standardize naming across providers (e.g., unify region names across AWS, GCP, and Azure)
  * AI-powered similarity detection suggests values that should be grouped together, reducing manual effort
  * Drag-and-drop reordering to organize your engineered labels

  Preview label values and their cost impact before saving, with full data inspection modals for deeper analysis.

  <img alt="Dimensions label inspector" />
</Update>

<Update label="Feb 5 2026">
  ## Smarter Alerts for Cost and Budget Monitoring

  Stay ahead of cost anomalies with a redesigned alerts system supporting multiple alert types and notification channels:

  <img alt="Create Alert with templates" />

  * Cost Alerts monitor actual spending against custom thresholds — get notified when costs spike or drop unexpectedly
  * [Budget Alerts](/use-cases/automate_budget) track spend against allocated budgets with percentage-based triggers and automatic owner notifications
  * Multi-threshold severity levels (Info, Warning, Alert) with daily, weekly, or monthly evaluation periods

  <img alt="Create Alert with templates" />

  Deliver alerts directly to Slack channels or email recipients across your organization. Snooze alerts when needed, review historical triggers, and use pre-configured templates to get started quickly.

  Weekly cumulative sums let you track running totals over the current week, so you can catch budget overruns before the month closes.

  <img alt="Weekly cumulative sum alerts" />
</Update>

<Update label="Feb 2 2026">
  ## Dashboards with Explorer

  Dashboards can now be edited in-line in [Explorer](/features/cost-explorer), allowing you to change titles, resize tiles, and add and delete widgets with fewer clicks. Further changes:

  * Creating a dashboard widget no longer requires saving a view
  * Dashboards now support Text widgets for additional context
  * Templates allowing you to get started faster than ever

  <img alt="Dimensions page" />
</Update>

<Update label="Jan 30 2026">
  ## Introducing the new Explorer

  [Explorer](/features/cost-explorer) shows where your cloud spend goes and adds multiple metrics, formulas, anomaly drill-downs, and reusable views.

  <img alt="Explorer overview" />

  * **Multiple Metrics**: Plot cost alongside usage metrics, business KPIs, or custom data on the same chart. Each metric gets its own axis.
  * **Ad-hoc Formulas**: Create calculated fields like cost-per-user or cost-per-request. Combine any metrics with arithmetic operations.
  * **Aggregations**: Go beyond sum. Use average, max, or min to analyze your data the way you need.

  <img alt="Query modifiers" />

  **Flexible Comparison**: Enable comparison mode to see a waterfall chart breaking down exactly what changed between two time periods. Sort by absolute or percentage change.

  <img alt="Flexible comparison" />

  **Undo/Redo** — Cmd+Z to undo, Cmd+Shift+Z to redo. Explore freely without losing your work.

  <img alt="Undo and redo" />

  **Time Navigation** — Arrow buttons slide your view backward or forward by one period. Last month becomes the month before with a single click.

  <img alt="Time navigation" />
</Update>

<Update label="Jan 23 2026">
  ## Stay Connected with Teams

  Send digests and alerts directly to Teams channels alongside [Slack](/features/slack-reports).

  <img alt="AWS setup flow" />

  Keep your entire organization informed about cost changes and anomalies in the collaboration tools they already use.
</Update>

<Update label="Jan 16 2026">
  ## New Setup Flows for AWS and Azure

  Step-by-step setup flows for [AWS](/setup/billing#aws) and [Azure](/setup/billing#azure) with copy-paste commands and real-time validation. Our guided wizards walk you through creating cost exports and configuring permissions, with instant feedback to ensure everything is set up correctly.

  <img alt="Alerts configuration" />

  For [AWS](/setup/billing#aws), you can now set up billing exports using a one-click CloudFormation stack. The template creates the CUR 2.0 export and configures the IAM role with the required permissions automatically.
</Update>

<Update label="Jan 9 2026">
  ## Daily Scheduled Reports

  [Scheduled reports](/features/slack-reports) now support daily frequency, so you can receive cost summaries every morning alongside your existing weekly and monthly schedules.
</Update>

<Update label="Dec 26 2025">
  ## Fully Automated Digest

  [Digests](/features/digest) are now fully automated — configure once and Costory generates your cost reports on schedule with background processing. Each digest includes markdown-rendered analysis with auto-generated charts, organized in a 5-step config modal for quick setup.

  <img alt="Fully automated digest configuration" />
</Update>

<Update label="Dec 16 2025">
  ## Amplitude Integration

  Correlate product usage with cloud costs. Connect your [Amplitude](/use-cases/amplitude/cost_per_active_users) project to bring [Daily Active Users](/setup/usage-metrics) into Costory, then visualize usage trends alongside infrastructure spend. Supports both US and EU data regions with 12 months of historical data synced automatically.

  <img alt="Amplitude integration" />
</Update>

<Update label="Dec 11 2025">
  ## Meet Costory Spotlight

  Press **Cmd/Ctrl+K** from anywhere to open Spotlight and navigate directly to your most-used views and features. Start typing to search across dashboards, saved views, metrics and more. Arrow keys navigate, Enter opens, Escape closes.

  <img alt="Costory Spotlight search" />

  Spotlight adapts to your usage — you'll see your recent dashboards, recently accessed views, and the most popular views across your team from the last 30 days. Community templates give you ready-to-use starting points for common analyses.

  <img alt="Spotlight quick actions" />
</Update>

<Update label="Dec 5 2025">
  ## Smarter Cost Analysis with Costory AI

  Costory AI got a major upgrade to how it understands and navigates your cost data. Improved vocabulary and column-naming awareness means Costory AI now interprets dimensions, labels, and groupings more accurately — fewer false leads, more relevant breakdowns.

  Under the hood, heavy columns are now tokenized for faster processing, and a new prompt architecture gives Costory AI better guidance on when to drill deeper versus when to surface results. Combined with the group-by quality scoring introduced in November, Costory AI's investigations are sharper and faster than ever.
</Update>

<Update label="Nov 27 2025">
  ## Streamlined Onboarding

  Organization creation is now fully automated during sign-up — no manual steps required. The onboarding flow also supports organization hierarchies for teams managing parent and child accounts, with smarter defaults and improved invite handling.
</Update>

<Update label="Nov 20 2025">
  ## Multi-Org Support, Exports & Quality of Life

  * **Multi-organization support** — manage multiple organizations from a single account and switch between them seamlessly
  * **Cleaner PNG exports** — exports now match exactly what you see on screen, with proper borders and shadows
  * Rename metrics without recreating them, and delete dashboards and views from anywhere
</Update>

<Update label="Nov 7 2025">
  ## A New Look for Costory AI

  Costory AI now generates full markdown for each node with **dynamic chart generation**. After identifying contributing factors for a cost spike, Costory AI picks the most relevant dimension to visualize the underlying cost drivers at a glance.

  <img alt="Costory AI dynamic chart generation" />

  The digest modal got a visual refresh — cleaner layout, easier navigation, and quick toggles to show or hide charts while reading.

  <img alt="Costory AI report nodes" />

  **Interactive Feedback and Continuity** — provide feedback to Costory AI and specify how to update an existing report. Costory AI regenerates each node according to your specifications, and all previous versions are saved so you can pick up where you left off.

  <img alt="Costory AI interactive feedback" />
</Update>

<Update label="Nov 5 2025">
  ## Under the Hood: Costory AI Becomes your FinOps Agent

  Costory AI evolved from a fixed analysis pipeline into an autonomous AI agent powered by Gemini. Instead of following predetermined steps, Costory AI now reasons about your data — deciding which dimensions to investigate, which statistical tests to run, and how to present findings.

  Key changes under the hood:

  * **Tool-based architecture** — Costory AI has its own toolbox: assess group-by quality, fetch timeseries, run contributing factor analysis, and pull historical cost context
  * **Statistical dimension selection** — a concentration index scores each dimension before Costory AI drills in, so analysis focuses on what actually explains cost changes
  * **Parallel data fetching** — timeseries queries now run concurrently, cutting investigation time significantly
  * **Events & knowledge retrieval** — Costory AI can now pull events and organizational knowledge directly into its analysis, cross-referencing deployments, incidents, and internal context for richer explanations
</Update>

<Update label="Oct 30 2025">
  ## A New Look for the Explorer and Dashboards

  The library is now **keyboard-first** — navigate everything with **Cmd/Ctrl+K**, arrow keys, and shortcuts. Consistent color schemes across all charts make it easier to track dimensions visually.

  <img alt="Explorer library view" />

  The query builder has been updated with a cleaner interface, and you can now **filter dashboards by view** to focus on the data that matters most.

  <img alt="Inline dashboard editing" />

  Inline editing lets you modify dashboards without leaving the page, and you can create new views directly from within dashboards. Change the time period on any dashboard without leaving the page, and create saved views straight from the dashboard modal.

  <img alt="Dashboard widget types" />
</Update>

<Update label="Oct 15 2025">
  ## Consistent Color Palette & Mobile Sign-Up

  All charts now use a consistent color palette with full hex color support, making it easier to track dimensions visually across views and dashboards. The sign-up page is also now fully optimized for mobile.

  <img alt="Keyboard-first library" />
</Update>

<Update label="Oct 8 2025">
  ## Aiven Billing Integration

  Track your Aiven managed service costs alongside other cloud providers. Billing data syncs automatically with full historical import.

  <img alt="Aiven billing integration" />
</Update>

<Update label="Oct 1 2025">
  ## Redesigned Onboarding & Sign-Up

  A completely overhauled onboarding flow with automated organization creation, smarter defaults (start date now defaults to 3 months ago), and a redesigned sign-up page optimized for mobile. Setup wizards now link directly to the relevant documentation.
</Update>

<Update label="Sep 17 2025">
  ## Event Correlations & Advanced Cost Metrics

  **[Events](/setup/events) Correlations in the Digest** — correlated events now appear for every cost change and trend, helping you identify root causes and share findings with your organization.

  <img alt="Cost dimension mapping" />

  Also new: **GBP currency support** and advanced AWS [cost metrics](/docs/cost-metrics) including Unblended, Net Unblended, Amortized, and Net Amortized cost views. The "Others" category in the explorer now shows up to 200 items for deeper analysis.

  <img alt="Event correlations" />
</Update>

<Update label="Sep 4 2025">
  ## Dimensions in Labels Explorer

  Introducing **[Dimensions](/features/tagging/dimensions)** in the Labels Explorer, a way to standardize and transform cost labels across all cloud providers.

  * **Select & Merge Labels**: choose multiple labels from different sources and merge them into a single, unified label
  * **Map Values**: standardize disparate values (e.g., map "prod", "production", "prd" all to "Production")
  * **Name & Save**: give your new label a clear name and save it for use across all analyses

  <img alt="Dimensions mappings" />
</Update>

<Update label="Aug 29 2025">
  ## Trends Detection & New Charts

  Costory AI now analyzes your spending and overlays **trends directly on charts**, helping you distinguish signal from noise. In digests, trend charts with event markers let you correlate changes with deployments, incidents, or infrastructure updates.

  <img alt="Interactive chart legends" />

  PNG exports now include event markers with labels and descriptions, rendered with smart positioning — making exported charts presentation-ready with full context.

  **Better chart controls** — interactive legends let you highlight series on hover and hide/show specific data by clicking. Tooltips sort values in descending order for quick identification of top contributors.

  <img alt="Event correlations in charts" />
</Update>

<Update label="Aug 5 2025">
  ## Digests Redesigned

  **Digests redesigned from the ground up** — a cleaner modal with badge-based organization. Collapse and expand sections as you review, with "Expand All" / "Collapse All" for quick navigation. **Compare periods side by side** with current month in solid blue and previous in dashed gray, with percentage changes in tooltips.

  <img alt="Comparison charts" />
</Update>

<Update label="Jul 30 2025">
  ## Datadog Billing & Events in Saved Views

  **Datadog billing integration** — track observability costs alongside cloud infrastructure with a setup wizard supporting both US and EU instances.

  **[Events](/setup/events) in saved views** — bookmark deployments, incidents, and releases to have them automatically appear on relevant dashboards. Event filters now save with your views.

  <img alt="Events in saved views" />
</Update>

<Update label="Jul 17 2025">
  ## Costory AI Investigates Your Cost Spikes

  When Costory detects unusual spending, Costory AI automatically analyzes the spike and identifies contributing factors — within minutes. The analysis appears directly in your digest and respects your exclusion filters, so you only see what matters.

  <img alt="Costory AI cost spike analysis" />
</Update>

<Update label="Jun 26 2025">
  ## Modern Group By & Events from Anywhere

  The redesigned **group by** widget uses color-coded pills for different dimension categories (Infrastructure, Applications, etc.). Search finds dimensions by their actual values, not just names — searching "prod" finds dimensions containing "production" values. Full keyboard navigation makes exploration fast.

  <img alt="Dimension search" />

  **[Events](/setup/events) from anywhere** — create events via public API from CI/CD pipelines, monitoring tools, or ticketing systems. Track AWS price changes, Reserved Instance purchases, and Savings Plan commitments automatically. GitHub integration monitors pull request merges, repository creation, and releases.
</Update>

<Update label="Jun 19 2025">
  ## AI Suggests the Dimensions That Matter

  Costory AI now analyzes your data and suggests the most relevant dimensions to group by. The **suggested axes** feature scores dimensions by impact, showing which ones have the highest explanatory power. A sparkle icon marks suggestions, and you can auto-select them for instant insights.

  <img alt="AI dimension suggestions" />
</Update>

<Update label="Jun 2 2025">
  ## Confluent Cloud, Split Costs & Integration Improvements

  **Confluent Cloud billing** with automated BigQuery sync and historical data import. Datadog metrics got centralized configuration with faster previews. Custom BigQuery mappings now support 40+ fields.

  **[Split costs](/use-cases/allocate_shared_cloud_sql_database/allocate) by actual usage** — allocate shared costs based on telemetry from Datadog, CSV, Google Sheets, AWS, or CI visibility metrics. Map cost centers to usage metrics with visual previews showing top consumers over time.

  <img alt="Dynamic allocation configuration" />
</Update>

<Update label="May 30 2025">
  ## Track Costs Alongside Deployments, Incidents, and Releases

  Track deployments, incidents, and releases directly on your cost charts. [Events](/setup/events) appear as visual markers on timelines, letting you instantly correlate cost spikes with real-world changes. Organize events into **BUSINESS**, **TECHNICAL**, and **PROVIDER** categories with reusable labels across your organization.

  <img alt="Events on cost charts" />
</Update>

<Update label="May 22 2025">
  ## Introducing the Costory Digest

  Engineering teams shouldn't have to dig through dashboards every month to figure out what changed. The [Costory Digest](/features/digest) does the work for you — it automatically analyzes your cloud costs, identifies the biggest movers, and delivers a clear summary straight to [Slack](/features/slack-reports) on your schedule.

  <img alt="Costory Digest" />

  * **Configurable scope** — choose the time period, group-by dimensions, and filters to match what matters to your team
  * **Interactive charts** with trend lines that highlight cost movements at a glance
  * **"Others" rollup** so smaller line items don't clutter the picture
  * **Drawer view** for quick exploration without leaving your workflow
  * **Scheduled delivery to Slack** so your Monday morning standups always start with the full picture
</Update>


# Cost Metrics
Source: https://docs.costory.io/docs/cost-metrics

How we compute the different metrics on top of your billing data

# Cost Metrics

* **Cost (Billed Cost)**: The amount you actually pay at the end of the month, after all discounts and credits have been applied.
* **Effective Cost**: The billed cost with upfront fees for Savings Plans and Reserved Instances spread (amortized) evenly across the commitment period, instead of being charged as a lump sum. This gives you a smoother, more representative view of daily costs.
* **List Cost**: The cost calculated from public on-demand prices, what you would have paid without any negotiated discounts or commitments. Use this as a benchmark to measure how much you're saving compared to standard pricing.
* **Contracted Cost**: The cost under your negotiated <Tooltip href="/docs/glossary#edp">EDP</Tooltip> or special pricing, excluding all <Tooltip href="/docs/glossary#savings-plans">Savings Plan</Tooltip> discounts and credits. This isolates the effect of actual usage changes from discount movements.
  <Tip>
    We advise to track Contracted Cost for your engineering team since it only
    depends on actual usage. Tracking Billed Cost can be misleading because of
    Savings Plan reassignments and credits you receive during the year.
    [Learn why Contracted Cost is the right metric for engineering teams](/docs/savings-plan-cost-fluctuation)
  </Tip>

## AWS

| AWS Cost Explorer Metric / Field | Costory Equivalent | Adjustments    | Meaning                                                                                                        |
| -------------------------------- | ------------------ | -------------- | -------------------------------------------------------------------------------------------------------------- |
| Net Unblended Cost               | Cost (Billed Cost) | Taxes excluded | Matches the amount on your AWS invoice after all applied discounts and credits.                                |
| Net Amortized Cost               | Effective Cost     | Taxes excluded | Same as billed cost but with upfront RI/Savings Plan fees spread evenly across the covered period.             |
| (No AWS equivalent)              | List Cost          | Taxes excluded | Cost calculated from AWS public list prices × usage quantity. Ignores all EDP, RI, and Savings Plan discounts. |
| (No AWS equivalent)              | Contracted Cost    | Taxes excluded | Cost under your negotiated EDP or special pricing, excluding all Savings Plan discounts and credits.           |

## GCP

| GCP Billing Field                  | Costory Equivalent | Adjustments    | Meaning                                                                                                                      |
| ---------------------------------- | ------------------ | -------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| Cost including all credits and CUD | Cost (Billed Cost) | Taxes excluded | Total cost including all credits (promotions, SUD, CUD, reseller margin). Matches your GCP invoice.                          |
| Cost including all credits and CUD | Effective Cost     | Taxes excluded | Same as billed cost. GCP does not separate amortized vs non-amortized costs.                                                 |
| cost\_at\_list                     | List Cost          | Taxes excluded | Cost calculated from GCP public list prices. Only applies to regular cost rows, not credits.                                 |
| (No GCP equivalent)                | Contracted Cost    | Taxes excluded | Cost excluding promotions, SUD, subscription benefits, reseller margin, and CUD credits. Commitment costs are also excluded. |

## Azure

| Azure Cost Management Field | Costory Equivalent | Adjustments    | Meaning                                                                                                                                           |
| --------------------------- | ------------------ | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| Actual Cost (costInUsd)     | Cost (Billed Cost) | Taxes excluded | Matches the amount on your Azure invoice. Uses the "actual" cost export.                                                                          |
| Amortized Cost (costInUsd)  | Effective Cost     | Taxes excluded | Same as billed cost but with upfront reservation and savings plan fees spread evenly across the covered period. Uses the "amortized" cost export. |
| PayG Cost (paygCostInUsd)   | List Cost          | Taxes excluded | Cost calculated from Azure pay-as-you-go rates before any discounts.                                                                              |
| Actual Cost (costInUsd)     | Contracted Cost    | Taxes excluded | Same as billed cost. Azure does not provide a separate contracted rate equivalent.                                                                |

<Note>
  For Azure, Contracted Cost is identical to Billed Cost because Azure does not expose a separate contracted or negotiated rate in its billing exports. This means the Contracted Cost advantage (isolating usage changes from discount movements) does not currently apply to Azure.
</Note>

## Datadog

| Datadog Billing Field | Costory Equivalent | Adjustments | Meaning                                                                                                           |
| --------------------- | ------------------ | ----------- | ----------------------------------------------------------------------------------------------------------------- |
| billed\_cost          | Cost (Billed Cost) | None        | The amount billed by Datadog for the usage period.                                                                |
| effective\_cost       | Effective Cost     | None        | Same as billed costs, but your commitments that can be amortized are spread out per day based on the actual usage |
| billed\_cost          | List Cost          | None        | Same as billed cost. Datadog does not provide separate list pricing.                                              |
| billed\_cost          | Contracted Cost    | None        | Same as billed cost. Datadog does not distinguish contracted vs standard pricing.                                 |


# Cloud Cost Currency Conversion
Source: https://docs.costory.io/docs/currency-conversion

Cloud cost currency conversion and reporting currency rules for AWS, GCP, Azure, and Datadog in Costory.

Cloud cost currency conversion lets you compare AWS, GCP, Azure, and Datadog spend in a single reporting currency. Costory normalizes each provider's billing export and applies the appropriate exchange-rate policy for that source.

<Frame>
  <img alt="Cloud cost currency conversion lets you compare AWS, GCP, Azure, and Datadog spend in a single reporting currency." />
</Frame>

## Supported currencies

Costory supports the following reporting currencies today:

* USD
* EUR
* GBP

<Note>
  Need another currency? Contact Costory support and we will confirm coverage and timing.
</Note>

## Set your reporting currency in Costory

<Steps>
  <Step title="Open Settings">
    In Costory, open <strong>Settings</strong> for your organization.
  </Step>

  <Step title="Choose a reporting currency">
    Select <strong>Reporting currency</strong> and choose USD, EUR, or GBP.
  </Step>

  <Step title="Save and refresh reports">
    Newly processed data, dashboards, and exports will use the selected currency.
  </Step>
</Steps>

## Provider-specific conversion rules

| Provider | How the provider sets currency/rate                                                                               | Shared in export?                                                                             | How Costory handles conversion                                                                                                                                                                                                                         |
| -------- | ----------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| AWS      | AWS converts USD totals to your preferred currency using the exchange rate in effect when the invoice is created. | No. <Tooltip href="/docs/glossary#cur">CUR</Tooltip> 2.0 does not include the currency rate.  | During the month (before the invoice is finalized), Costory uses an estimated exchange rate from public data sources ([Google Finance](https://www.google.com/finance/)). At the end of the month, Costory uses the exchange rate at the invoice date. |
| GCP      | The exchange rate is set at the beginning of the month and stays constant for the whole month.                    | Yes. GCP includes the currency rate in the billing export.                                    | Costory uses the provided monthly exchange rate directly.                                                                                                                                                                                              |
| Azure    | Azure provides both billing currency and pricing currency, which implies a conversion rate.                       | Yes, indirectly. The rate is inferred from billing and pricing currency values in the export. | Costory uses the inferred currency rate directly.                                                                                                                                                                                                      |
| Datadog  | Usage is billed in USD.                                                                                           | No explicit conversion rate in the usage export.                                              | Costory uses an estimated exchange rate from public data sources ([Google Finance](https://www.google.com/finance/)).                                                                                                                                  |

## FAQ

<AccordionGroup>
  <Accordion title="When does the exchange rate update?">
    For providers that include a rate in the export (GCP and Azure), Costory
    follows the provider cadence. For AWS and Datadog, Costory refreshes
    estimated rates as new billing data is ingested, and AWS rates are finalized
    to the invoice-date rate once the invoice closes.
  </Accordion>

  <Accordion title="How accurate is the estimated rate?">
    Estimated rates come from Google Finance and are intended for directional
    reporting. The final AWS invoice rate can differ.
  </Accordion>
</AccordionGroup>

## Related pages

* [Cost Metrics](/docs/cost-metrics)


# Billing Data Refresh Schedule and Cloud Cost Data Freshness
Source: https://docs.costory.io/docs/data-refresh

Costory's billing data refresh schedule, including the monthly refresh window and AWS/GCP billing data freshness.

# Billing Data Refresh Schedule and Cloud Cost Data Freshness

This page explains Costory's billing data refresh schedule and cloud cost data
freshness: when billing updates arrive and what to expect from AWS CUR and GCP
billing exports.

## Monthly billing data refresh window

* Costory refreshes month **n-1** until the **10th of month n**.
* After the 10th, Costory freezes month n-1 so month-close numbers stay stable.
* Providers often post late adjustments in the first few days of the new month.

<Tip>
  If you need finalized month-close numbers, plan to review the prior month after
  the 10th.
</Tip>

## AWS and GCP billing data freshness

Costory refreshes billing data every morning. Because providers deliver exports
with a delay, you typically see full data for <strong>d-2</strong> and partial
data for <strong>d-1</strong>, where <strong>d</strong> is today. For example, if
today is the 10th, you should expect complete data through the 8th.

| Provider | Provider export timing                                           | What you see in Costory                                                   |
| -------- | ---------------------------------------------------------------- | ------------------------------------------------------------------------- |
| GCP      | Around T+12 hours on average.                                    | Full data for d-2, partial data for d-1.                                  |
| AWS      | 12 to 24 hours, with exports generated every 6 hours by default. | Full data for d-2, partial data for d-1 (depends on the last export run). |

## Related pages

* [Billing Providers](/setup/billing)
* View the <Tooltip href="/docs/glossary#cost-explorer">Explorer</Tooltip> feature overview in the [feature page](/features/cost-explorer).


#  
Source: https://docs.costory.io/docs/finops-memes

 

<div>
  <div>
    <img alt="Prison Mike FinOps meme" />
  </div>

  <div>
    <img alt="Bad Luck Brian FinOps meme" />
  </div>

  <div>
    <img alt="Prison bus FinOps meme" />
  </div>

  <div>
    <img alt="Waiting skeleton FinOps meme" />
  </div>

  <div>
    <img alt="Digital transformation cloud bill meme" />
  </div>

  <div>
    <img alt="Cloud budget surprise meme" />
  </div>

  <div>
    <img alt="Be like Bill FinOps meme" />
  </div>

  <div>
    <img alt="FinOps reporting meme" />
  </div>

  <div>
    <img alt="FinOps pricing meme" />
  </div>

  <div>
    <img alt="Trade offer FinOps meme" />
  </div>

  <div>
    <img alt="Cloud spend spike meme" />
  </div>
</div>


# Glossary
Source: https://docs.costory.io/docs/glossary

Definitions for FinOps, cloud billing, and Costory-specific terms used throughout this documentation

## Costory Concepts

<AccordionGroup>
  <Accordion title="Explorer">
    Costory's main interface for exploring cloud costs across all connected providers. Supports filtering, grouping by any dimension, multiple metrics, formulas, event overlays, drill-downs, saved views, alerts, and dashboard creation. Not to be confused with AWS Cost Explorer, which is AWS's own native billing tool.

    Related: [Explorer](/features/cost-explorer)
  </Accordion>

  <Accordion title="Digest">
    A Cost Report element that breaks period-over-period cost changes into a tree by the dimensions you choose (for example provider, team, service name, or project), ranks movers by dollar impact, and can attach an AI narrative for Slack, email, and in-app Summary, Tree, or Table views.

    Related: [Digest](/features/digest) | [Cost Reports](/v2/Automate/reports) | [Monthly Cloud Cost Reporting](/automate-reporting/monthly-reviews)
  </Accordion>

  <Accordion title="Cost Breakdown Tree">
    The hierarchical structure used in a Cost digest to organize cost data. Report Group By sets the first level. Additional group-by dimensions add deeper levels (for example Provider, then Environment, then Service Name).

    Related: [Digest](/features/digest) | [Monthly Cloud Cost Reporting](/automate-reporting/monthly-reviews)
  </Accordion>

  <Accordion title="Dashboard">
    A saved view made of one or more Explorer widgets. Each widget keeps its own metric, formula, filters, group-by, selected period, and event context.

    Related: [Dashboards](/features/dashboards)
  </Accordion>

  <Accordion title="Dimensions">
    Costory reporting fields used to filter, group, allocate, scope, alert, and report on costs. A dimension can merge several native tags or labels into one field, such as `aws:Environment`, `env`, and `environment` into `Environment`.

    Related: [Dimensions](/features/tagging/dimensions) | [Env Allocation](/use-cases/automated_env_allocation/visibility) | [EKS cost allocation](/use-cases/eks-cost-allocation)
  </Accordion>

  <Accordion title="Virtual dimensions">
    Rule-based dimensions whose output values are defined in Costory. For example, a `Team` virtual dimension can route rows where `project_id` starts with `eng-` to `Engineering`, and route everything else to `Platform` without requiring that tag to exist in any cloud account.

    Related: [Dimensions](/features/tagging/dimensions#virtual-dimensions) | [Shared Cost Allocation](/use-cases/allocate_shared_cloud_sql_database/allocate) | [Reallocate API Costs](/use-cases/reallocate_api_costs)
  </Accordion>

  <Accordion title="Dynamic Allocation">
    A virtual dimension option that splits shared costs proportionally based on actual usage data (e.g., storage or CPU usage per team) rather than fixed rules. Used when a shared resource like a database serves multiple teams.

    Related: [Shared Cost Allocation](/features/tagging/shared-cost-allocation) | [Dimensions](/features/tagging/dimensions) | [Reallocate API Costs](/use-cases/reallocate_api_costs)
  </Accordion>

  <Accordion title="Standard Columns">
    Costory's unified billing schema. All normalized fields are prefixed with `cos_` so you can query across AWS, GCP, and Azure using the same field names instead of learning each provider's billing export format.

    Related: [Standard Columns](/docs/standard-columns)
  </Accordion>

  <Accordion title="Scheduled Report">
    An automatically recurring cost report delivered to Slack, Teams, or email on a weekly or monthly cadence. Created from any saved Explorer view.

    Related: [Cost Reports](/features/slack-reports) | [Decentralize FinOps](/automate-reporting/decentralize-finops)
  </Accordion>

  <Accordion title="View">
    A saved configuration of Explorer with specific metrics, filters, group-bys, date ranges, formulas, and event context. Views can be shared, scheduled as reports, or turned into dashboard widgets.

    Related: [Explorer](/features/cost-explorer) | [Dashboards](/features/dashboards) | [Cost Reports](/features/slack-reports)
  </Accordion>
</AccordionGroup>

***

## Cloud Billing

<AccordionGroup>
  <Accordion title="Cost Allocation">
    The process of assigning shared or untagged cloud costs to specific teams, products, or environments. The central challenge of FinOps. You can't optimize what you can't attribute.

    Related: [Tag & Allocate Costs](/features/tagging) | [Shared Cost Allocation](/features/tagging/shared-cost-allocation) | [Reallocate API Costs](/use-cases/reallocate_api_costs)
  </Accordion>

  <Accordion title="Chargeback">
    Billing internal teams for their actual share of shared cloud costs. Money moves between budgets. See also: [Showback](#showback).
  </Accordion>

  <Accordion title="Showback">
    Showing teams what they would be charged without actually moving money between budgets. Lighter than chargeback. The goal is awareness and accountability rather than internal billing.

    Related: [Decentralize FinOps](/automate-reporting/decentralize-finops)
  </Accordion>

  <Accordion title="Unit Economics">
    Financial metrics expressed on a per-unit basis: cost per customer, cost per API call, cost per transaction. They show whether you are getting more efficient as you scale, not just whether you are spending more.

    Related: [Unit Economics](/features/unit-economics) | [Relate Costs to Usage](/automate-reporting/unit-economics) | [Unit Economics with Amplitude](/use-cases/amplitude/cost_per_active_users)
  </Accordion>

  <Accordion title="Marginal Cost">
    The cost to serve one additional unit of value: one more user, one more customer, one more request. In cloud terms, production cost divided by your usage metric. Useful for exec reporting because it shows efficiency trends even when total spend grows.

    Related: [Executive Reporting](/use-cases/what_your_exec_team_wants/value)
  </Accordion>

  <Accordion title="Cost Allocation Tags">
    Tags that cloud providers require you to explicitly activate before they appear in billing exports. In AWS, you must enable them in the Billing console. A common gotcha: you tagged your resources, but forgot to activate the tags for billing, so they don't show up in cost reports.

    Related: [AWS Setup](/setup/billing#aws)
  </Accordion>

  <Accordion title="CUR (Cost and Usage Report)">
    AWS's detailed billing export, the raw data source for AWS cost analysis. A Parquet file that contains every line item of your AWS bill. Costory ingests this automatically once connected.

    Related: [AWS Setup](/setup/billing#aws)
  </Accordion>

  <Accordion title="Split Cost Allocation">
    An AWS feature that breaks down container costs (EKS, ECS) to individual pod labels. Without this, you only see the total cost of the EC2 instances running your cluster, not what each workload costs. Must be enabled in AWS CUR settings.

    Related: [EKS cost allocation](/use-cases/eks-cost-allocation)
  </Accordion>
</AccordionGroup>

***

## Cloud Pricing

<AccordionGroup>
  <Accordion title="Unblended Cost">
    The sticker price: each resource billed at its standard on-demand rate, without applying any volume discounts or commitments. What you'd pay if you had no Savings Plans or Reserved Instances.

    Related: [Currency Conversion](/docs/currency-conversion)
  </Accordion>

  <Accordion title="Amortized Cost">
    Spreads upfront commitment payments (Savings Plans, Reserved Instances) evenly across the commitment period. Instead of showing a $36,000 spike on the purchase date, it shows $1,000/month for 3 years. Usually the most useful cost metric for monthly reporting.

    Related: [Currency Conversion](/docs/currency-conversion)
  </Accordion>

  <Accordion title="Net Unblended / Net Amortized Cost">
    The same as above, but after applying credits, EDP discounts, and refunds. Represents what you actually pay out of pocket. If your company has negotiated discounts with AWS, this is the number that matches reality.
  </Accordion>

  <Accordion title="Reserved Instances (RIs)">
    A commitment to use a specific instance type for 1 or 3 years in exchange for significant discounts (up to 72% off on-demand). Less flexible than Savings Plans, locked to a specific instance type and region.
  </Accordion>

  <Accordion title="Savings Plans">
    AWS's flexible commitment-based pricing. You commit to a consistent amount of compute usage (in \$/hour) for 1 or 3 years and get discounted rates. More flexible than RIs, not locked to a specific instance type. However, Savings Plan discounts can shift between accounts daily, causing misleading cost fluctuations. See [Why Contracted Cost](/docs/savings-plan-cost-fluctuation).
  </Accordion>

  <Accordion title="EDP (Enterprise Discount Program)">
    An AWS program where large customers commit to a minimum total spend in exchange for a blanket discount on all services. Typically negotiated annually. Costory's [Contracted Cost](/docs/savings-plan-cost-fluctuation) metric preserves EDP pricing while stripping out volatile Savings Plan discounts.
  </Accordion>

  <Accordion title="Credits">
    Discounts or promotional amounts applied to your cloud bill by the provider: startup credits, support credits, migration incentives. Important to track separately in exec reports because they mask true cost trends.

    Related: [Executive Reporting](/use-cases/what_your_exec_team_wants/value)
  </Accordion>

  <Accordion title="Marketplace Purchases">
    Third-party software bought through AWS, GCP, or Azure Marketplace (Datadog, MongoDB, etc.). These show up on your cloud bill but aren't infrastructure costs, often need to be excluded when calculating production cost metrics.
  </Accordion>
</AccordionGroup>

***

## Kubernetes Cost Terms

<AccordionGroup>
  <Accordion title="Requests vs. Limits">
    * **Requests**: the resources (CPU, memory) a pod guarantees it needs. Used for scheduling: the scheduler uses requests to decide which node a pod runs on.
    * **Limits**: the maximum a pod can consume before the kernel kills it.

    Costory calculates waste based on requests, not limits, because requests are what you're actually paying for on each node.

    Related: [K8s Waste Reduction](/use-cases/k8s_waste/visibility)
  </Accordion>

  <Accordion title="Waste (Kubernetes)">
    The gap between what your nodes provide and what your pods have requested. Formula: `available resources - total requests = waste`. Costory converts this to dollars using a 9:1 CPU-to-memory cost ratio. If your cluster has 40% waste, you're paying for 40% more capacity than your workloads need.

    Related: [K8s Waste Reduction](/use-cases/k8s_waste/visibility)
  </Accordion>

  <Accordion title="Waste Ratio">
    Waste expressed as a percentage of total cluster or node pool capacity. The key metric for identifying over-provisioned clusters.

    Related: [K8s Waste Reduction](/use-cases/k8s_waste/visibility)
  </Accordion>
</AccordionGroup>

***

## Reporting & Analysis

<AccordionGroup>
  <Accordion title="Anomaly Detection">
    Automatic identification of unusual cost spikes. Costory goes beyond simple threshold alerts by using ML models trained on your historical data, with seasonality awareness and event correlation, to determine whether a spike is genuinely abnormal.

    Related: [Monthly Cloud Cost Reporting](/automate-reporting/monthly-reviews)
  </Accordion>

  <Accordion title="Event Correlation">
    Aligning technical or business events (deployments, incidents, RI purchases, marketing campaigns) with cost timelines to explain why costs changed. Turns "costs went up 15%" into "costs went up 15% after the v2.3 deploy on Tuesday."

    Related: [Events](/features/events) | [Event Correlations](/automate-reporting/event-correlation) | [Events Setup](/setup/events)
  </Accordion>

  <Accordion title="Budget">
    A spending target set for a team, project, or cloud account over a given period. Costory lets you automate budget tracking by combining virtual dimensions with scheduled reports, so stakeholders get alerted before overruns happen, not after the invoice arrives.

    Related: [Automate Budget Tracking](/use-cases/automate_budget)
  </Accordion>

  <Accordion title="FP&A (Financial Planning & Analysis)">
    The finance function responsible for budgeting and forecasting. The people who will ask you "why did cloud costs go up?" and expect a number, not a Grafana dashboard. Costory helps you speak their language.
  </Accordion>

  <Accordion title="Waterfall Chart">
    A visualization showing how individual factors contribute to an overall change: which services, accounts, or teams drove a cost increase or decrease. Answers "where did the extra \$10k come from?" at a glance.

    Related: [Explorer](/features/cost-explorer)
  </Accordion>
</AccordionGroup>


# Contracted Cost vs Billed Cost: Savings Plan discount sharing issues
Source: https://docs.costory.io/docs/savings-plan-cost-fluctuation

Learn why Contracted Cost gives platform and engineering teams a stable, usage-driven view of AWS and GCP cloud spending, avoiding misleading Savings Plan cost fluctuations.

# Contracted Cost vs Billed Cost: Stable Cloud Cost Metrics

## Why Billed Cost Is Misleading When Using AWS Savings Plans

If you're a **platform engineer**, **SRE**, or **engineering manager** responsible for cloud costs, you've probably seen cost dashboards that don't match reality. The root cause is often how your cloud provider allocates Savings Plan discounts, not anything your team actually changed.

When you purchase a <Tooltip href="/docs/glossary#savings-plans">Savings Plan</Tooltip> (AWS) or Committed Use Discount (GCP) that covers multiple accounts or projects, the cloud provider can reassign which resources benefit from the discount over time. This means the **Billed Cost** for a given account, cluster, or service can fluctuate significantly, even when actual usage hasn't changed at all.

This is a well-documented challenge in cloud cost management. AWS itself acknowledged it by launching [RI & Savings Plans Group Sharing](https://aws.amazon.com/blogs/aws-cloud-financial-management/control-your-aws-commitments-with-risp-group-sharing/) to give organizations more control over discount allocation. Google Cloud offers [CUD attribution modes](https://cloud.google.com/docs/cuds-attribution) (proportional and prioritized) to mitigate unpredictable cost fluctuations across projects. The [FinOps Foundation](https://www.finops.org/wg/commitment-based-discounts-overview/) also highlights this as a core challenge: commitment discounts often apply across an organization's hierarchy in ways that don't align with actual resource consumption. AWS even published a dedicated guide on [building a Savings Plan chargeback strategy](https://aws.amazon.com/blogs/aws-cloud-financial-management/aws-savings-plans-how-to-implement-an-effective-chargeback-strategy/) to redistribute costs after the fact.

Costory fixes this problem with a simple approach: **Contracted Cost** strips discounts out entirely so you see only what your usage would cost under your negotiated rates, with no redistribution logic and no assumptions about Savings Plan discount allocation. For a full comparison of all cost metrics, see [Cost Metrics](/docs/cost-metrics).

### Example: Savings Plan moves between Kubernetes clusters

Imagine you have two EKS clusters and a global Savings Plan:

|                                 | Cluster A                        | Cluster B                             |
| ------------------------------- | -------------------------------- | ------------------------------------- |
| **Before SP move** (Jan 1 to 7) | SP applied, **\$2,000/day**      | No SP, **\$3,000/day**                |
| **After SP move** (Jan 8 to 14) | No SP, **\$2,600/day** (+30% 🔴) | SP applied, **\$2,400/day** (-20% 🟢) |

If you track **Billed Cost**, Cluster A appears to spike +30% overnight. Your platform team opens an incident, engineers start investigating, but there's nothing to find. The actual usage hasn't changed, only which cluster receives the SP discount. This is wasted engineering time caused by unreliable cost data.

<Frame>
  <img alt="Bar chart showing misleading cost spike in Cluster A and drop in Cluster B when Savings Plan is reassigned" />
</Frame>

## What Is Contracted Cost and How It Solves This

**Contracted Cost** is a cloud cost management metric that strips out all Savings Plan discounts and credits, but keeps your negotiated <Tooltip href="/docs/glossary#edp">EDP</Tooltip> pricing. This gives you a stable view of costs that only changes when actual usage changes, making it ideal for AWS cost optimization workflows.

<Frame>
  <img alt="Bar chart showing stable costs for both clusters regardless of Savings Plan movement" />
</Frame>

### GCP clarification: CUD movement has the same reporting risk

<Info>
  This feature is currently available for **AWS** only. While GCP has the same challenge with Committed Use Discounts moving across projects, Contracted Cost support for GCP is not yet available.
</Info>

* On GCP, Committed Use Discounts (CUDs) can move between projects over time, so **Billed Cost** per project can fluctuate even when usage is unchanged.
* CUD attribution modes (proportional vs. prioritized) affect how discounts are assigned and can make cost trends harder to interpret for engineering teams.
* Contracted Cost would provide the same stable, usage-driven view for GCP once supported.

<Tip>
  Use **Contracted Cost** as the default metric in any cost dashboard shared with engineering teams (e.g., team leads reviewing Kubernetes spend or SREs investigating cost anomalies).
  It ensures cost variations reflect real usage changes, not Savings Plan movements.
</Tip>

## How to Monitor Savings Plan Utilization Alongside Contracted Cost

Since Contracted Cost removes the [Savings Plan](https://docs.aws.amazon.com/savingsplans/latest/userguide/what-is-savings-plans.html) from the picture, you should separately monitor your Savings Plan utilization to catch:

* **Under-usage**: you're paying for a Savings Plan but not using enough eligible resources, so the commitment is wasted.
* **Over-usage**: your eligible usage exceeds your Savings Plan coverage, so you pay on-demand rates for the excess.

<Tip>
  Planning per-team cloud budgets? Contracted Cost is the recommended metric for team-level budgeting because it removes Savings Plan noise. See our step-by-step guide: [Automate your cloud budget](/use-cases/automate_budget).
</Tip>


# Identity and Access
Source: https://docs.costory.io/docs/sso-access-control

Compare Costory identity and access options across Copilot and Copilot Pro, including auto-join, single sign-on, directory sync, role-based access control, and security scope.

# Identity and Access

This page explains how identity and access work in Costory. It is for buyers comparing Copilot and Copilot Pro, IT or security reviewers checking access controls, and workspace admins deciding how users should join.

Authentication is handled by Clerk.

To invite users, click the **account name** in the left sidebar and open **Invites**. This is available to **Admin** users. For the full settings map, including domains and Costory product settings, see [Settings](/get-started/settings#invite-users).

## At-a-glance comparison

| Access area                    | Copilot, 250 EUR per month                                                                                                                                                                   | Copilot Pro, 1,000 EUR per month                                                                                                                                                                                                      |
| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Sign-in method                 | Users sign up with a company email address. This is not single sign-on (SSO).                                                                                                                | Users log in through your identity provider (IdP) using Enterprise SSO. Okta Workforce is supported natively through Security Assertion Markup Language (SAML) and OpenID Connect (OIDC). Any SAML or OIDC provider can be connected. |
| Who can join                   | Anyone with your approved company email domain, for example `name@acme.com`, is added to the workspace automatically. Public email providers such as Gmail or Outlook.com are not supported. | Users assigned in your IdP can log in through SSO. With directory sync, users can also be created before first sign-in.                                                                                                               |
| Provisioning                   | Auto-join by company domain. Clerk calls this Verified Domains.                                                                                                                              | Just-in-Time (JIT) provisioning creates the user and assigns a role at first SSO sign-in. System for Cross-domain Identity Management (SCIM) can create users in advance.                                                             |
| Deprovisioning and offboarding | No IdP-driven offboarding. Remove users in Costory when access should end.                                                                                                                   | SCIM removes users automatically when they leave your IdP, with no sign-in required. This is the path for prompt offboarding.                                                                                                         |
| Roles                          | Roles are managed in Costory. No IdP role mapping is included in this tier.                                                                                                                  | Role-based access control (RBAC), including role assignment through JIT provisioning.                                                                                                                                                 |
| Admin seats                    | Workspace admins are managed in Costory. The unlimited admin account guarantee applies to Copilot Pro.                                                                                       | Unlimited admin accounts at no extra cost. There is no per-admin fee.                                                                                                                                                                 |

<Warning>
  For a given workspace and domain, Auto-join by company domain and Enterprise SSO are mutually exclusive. You use one or the other on the same domain, not both. This is a Clerk limitation.
</Warning>

## Identity features by tier

<CardGroup>
  <Card title="Copilot: Auto-join by company domain" icon="envelope-circle-check">
    Let anyone with your company email domain join your Costory workspace without a manual invite.
  </Card>

  <Card title="Copilot Pro: Login through your identity provider" icon="shield-keyhole">
    Add login through an IdP, JIT provisioning, SCIM directory sync, RBAC, and unlimited admin accounts.
  </Card>
</CardGroup>

## Key concepts

### Auto-join by company domain

Auto-join by company domain adds users automatically when they sign up with your company email domain. Use it when you want low-friction access for a known company domain and do not need IdP-controlled sign-in.

This option is available on Copilot. It is not SSO, SAML, OIDC, or login through your provider.

### Login through your identity provider

Login through your identity provider lets users authenticate through your own IdP. Use it when your IT team requires centralized access policies, Okta Workforce, SAML, OIDC, role assignment, or automated offboarding.

This option is available on Copilot Pro. SAML is the usual Okta setup, but Okta Workforce is supported over both SAML and OIDC. Other SAML or OIDC identity providers can also be connected.

### JIT provisioning vs SCIM directory sync

JIT and SCIM both create user accounts, but they solve different operational problems. In Clerk, SCIM directory sync is called Directory Sync.

| Provisioning option | What happens                                                                                            | Offboarding impact                                                                                  |
| ------------------- | ------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| JIT provisioning    | A user account is created and a role is assigned the first time the user signs in through SSO.          | The user must sign in before the account exists. JIT alone is not the prompt offboarding path.      |
| SCIM directory sync | Costory stays aligned with your IdP. Users are created in advance and removed when they leave your IdP. | Users are removed automatically with no sign-in required. Use SCIM when prompt offboarding matters. |

<Tip>
  If your security review focuses on leavers and access removal, evaluate SCIM first. It is the feature that keeps Costory aligned with your identity provider without waiting for user sign-in.
</Tip>

## Which should you choose?

Choose Copilot if:

* You want users with a real company email domain to join automatically.
* You do not need SSO, SAML, OIDC, SCIM, or IdP-managed offboarding.
* You can remove users directly in Costory when access should end.

Choose Copilot Pro if:

* You use Okta Workforce, Azure AD / Entra, Google Workspace, OneLogin, or another SAML or OIDC provider for workforce access.
* You need SSO, JIT provisioning, SCIM directory sync, RBAC, or unlimited admin accounts.
* You need automatic removal when users leave your IdP.

## Security and data scope

Costory ingests only cloud billing and usage data:

* Cost line items per service, team, and resource.
* No end-user personally identifiable information (PII).
* No customer application data.
* No other sensitive business data.

Access to connected cloud accounts is read-only.

Costory runs on Google Cloud Platform (GCP), with encryption in transit and at rest. Clerk handles authentication. Clerk is Service Organization Control 2 (SOC 2) Type II certified and compliant with the Health Insurance Portability and Accountability Act (HIPAA), General Data Protection Regulation (GDPR), and California Consumer Privacy Act (CCPA). Clerk also runs on GCP.

<Note>
  Costory itself is not yet certified for SOC 2 or International Organization for Standardization (ISO) 27001.
</Note>

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Do you support Okta?">
    Yes. Costory supports Okta Workforce natively on Copilot Pro through SAML and OIDC. SAML is the usual setup. Any SAML or OIDC identity provider can be connected, not only Okta.
  </Accordion>

  <Accordion title="Should we use JIT or SCIM?">
    Use JIT when it is acceptable for users to be created at first SSO sign-in. Use SCIM when you need Costory to stay aligned with your IdP, create users in advance, and remove users automatically when they leave.
  </Accordion>

  <Accordion title="Are you SOC 2 or ISO 27001 certified?">
    Costory itself is not yet certified for SOC 2 or ISO 27001. Authentication is handled by Clerk, which is SOC 2 Type II certified and compliant with HIPAA, GDPR, and CCPA.
  </Accordion>

  <Accordion title="Do extra admins cost more?">
    No. Copilot Pro includes unlimited admin accounts at no extra cost. There is no per-admin fee.
  </Accordion>

  <Accordion title="What is the difference between auto-join and SSO?">
    Auto-join by company domain adds users who sign up with your approved company email domain. SSO lets users log in through your identity provider and is available on Copilot Pro.
  </Accordion>

  <Accordion title="Can I use both on the same domain?">
    No. For a given workspace and domain, Auto-join by company domain and Enterprise SSO are mutually exclusive. This is a Clerk limitation.
  </Accordion>
</AccordionGroup>


# Standard Columns
Source: https://docs.costory.io/docs/standard-columns

Costory normalizes billing data from AWS, GCP, Azure, Datadog, and Elastic Cloud into a unified schema. Here is how each column is populated per provider.

Costory ingests raw billing exports from each cloud provider and normalizes them into a consistent set of `cos_*` columns. This lets you query, filter, and group costs across providers using a single schema, so you don't need to learn each provider's billing format. For Elastic Cloud setup and grain (project × day × product line), see [Elastic Cloud billing](/setup/billing/elastic-cloud).

Columns are organized into the following categories:

| Category        | Description                                                                                                                   |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| **Invoice**     | Fields sourced directly from the provider billing export (accounts, charges, services, regions, resources, Kubernetes labels) |
| **Costory**     | Fields enriched by Costory (standardized region names, compute metadata, pricing model, marketplace flag)                     |
| **Datasources** | The Costory datasource that produced the row                                                                                  |

***

## Datasource & Provider Identification

### Invoice Issuer

The legal entity issuing the invoice, it also helps identifying marketplace purchases.

<Tabs>
  <Tab title="AWS">Sourced from `line_item_legal_entity`.</Tab>

  <Tab title="GCP">
    `"Google Cloud"` for first-party Google transactions (Compute Engine,
    Invoice service). For marketplace purchases, falls back to `seller_name` or
    `service.description`.
  </Tab>

  <Tab title="Azure">Hardcoded to `"Azure"`.</Tab>
  <Tab title="Datadog">Hardcoded to `"DataDog"`.</Tab>
  <Tab title="Elastic Cloud">Hardcoded to `"Elastic Cloud"`.</Tab>
</Tabs>

## Account & Billing

### Billing Account Id

The top-level billing or payer account.

<Tabs>
  <Tab title="AWS">`bill_payer_account_id`</Tab>
  <Tab title="GCP">`billing_account_id`</Tab>
  <Tab title="Azure">`BillingAccountId`</Tab>
  <Tab title="Datadog">`account_name`</Tab>
  <Tab title="Elastic Cloud">Elastic **project id** (`id` on the daily project snapshot).</Tab>
</Tabs>

***

### Sub Account ID / Project ID

The sub-account, project, or subscription under which the cost is incurred.

<Tabs>
  <Tab title="AWS">`line_item_usage_account_name`</Tab>
  <Tab title="GCP">`project.name` (falls back to `service.description`).</Tab>
  <Tab title="Azure">`SubscriptionName`</Tab>
  <Tab title="Datadog">`account_name`</Tab>
  <Tab title="Elastic Cloud">Elastic **project name** (`name`).</Tab>
</Tabs>

***

## Charge Classification

### Charge Category

Classifies the type of charge. Normalized to one of: `Usage`, `Purchase`, `Tax`, `Adjustment`.

<Tabs>
  <Tab title="AWS">
    Mapped from `line_item_line_item_type`: - `Usage`,
    `SavingsPlanCoveredUsage`, `SavingsPlanNegation`, `DiscountedUsage`,
    `BundledDiscount`, `Discount`, `PrivateRateDiscount`, `EdpDiscount` becomes
    **Usage** - `Fee`, `SavingsPlanUpfrontFee`, `RIFee`,
    `SavingsPlanRecurringFee` becomes **Purchase** - `Credit`, `Refund` becomes
    **Adjustment** - `Tax` becomes **Tax**
  </Tab>

  <Tab title="GCP">
    Mapped from `cost_type`: - `regular` becomes **Usage** - `tax` becomes **Tax** -
    `adjustment`, `credit`, `rounding_error`, and discount credit types becomes
    **Adjustment**
  </Tab>

  <Tab title="Azure">
    Mapped from `ChargeType`: - `Usage`, `UnusedReservation`,
    `UnusedSavingsPlan` becomes **Usage** - `Purchase` becomes **Purchase** - `Tax` becomes
    **Tax** - Everything else becomes **Adjustment**
  </Tab>

  <Tab title="Datadog">Always **Usage**.</Tab>
  <Tab title="Elastic Cloud">Always **Usage**.</Tab>
</Tabs>

***

### Charge Description

A human-readable description of the charge line item.

<Tabs>
  <Tab title="AWS">`line_item_line_item_description`</Tab>
  <Tab title="GCP">`sku.description`</Tab>
  <Tab title="Azure">`COALESCE(ProductName, ServiceName)`</Tab>
  <Tab title="Datadog">`charge_type`</Tab>
  <Tab title="Elastic Cloud">Full Elastic product line label for that line (same as **Service name**).</Tab>
</Tabs>

***

### Charge Frequency

How often the charge recurs. Normalized to: `One-Time`, `Recurring`, `Usage-Based`.

<Tabs>
  <Tab title="AWS">
    Based on `bill_bill_type`: - `Refund` or `Purchase` becomes **One-Time** -
    `Anniversary` becomes **Recurring**
  </Tab>

  <Tab title="GCP">Always **Recurring**.</Tab>

  <Tab title="Azure">
    Sourced from the `Frequency` field: - `OneTime` becomes **One-Time** - `Recurring`
    becomes **Recurring** - `UsageBased` becomes **Usage-Based**
  </Tab>

  <Tab title="Datadog">Always **Recurring**.</Tab>
  <Tab title="Elastic Cloud">Always **Usage-Based**.</Tab>
</Tabs>

***

## Service & SKU

### Category

A high-level cost category such as Compute, Storage, or Networking.
Mapped from a defined list of services.

<Tabs>
  <Tab title="AWS">Mapped from a defined list of services.</Tab>
  <Tab title="GCP">Mapped from a defined list of services.</Tab>
  <Tab title="Azure">Mapped from a defined list of services.</Tab>
  <Tab title="Datadog">Mapped from a defined list of services.</Tab>
  <Tab title="Elastic Cloud">Line **`type`** from the product line JSON (for example **`VCU`**, **`Search AI Lake`**, **`support`**).</Tab>
</Tabs>

***

### Service Name

The name of the cloud service.

<Tabs>
  <Tab title="AWS">
    `line_item_product_code` for first-party services. For marketplace,
    extracted from `product.key_value` (`product_name`).
  </Tab>

  <Tab title="GCP">`service.description`</Tab>
  <Tab title="Azure">`ConsumedService`</Tab>
  <Tab title="Datadog">`product_name`</Tab>
  <Tab title="Elastic Cloud">Full Elastic product line label for that line (for example `Elasticsearch - General Purpose - Search VCU (GCP us-central1)`).</Tab>
</Tabs>

***

### SKU ID

The SKU identifier.

<Tabs>
  <Tab title="AWS">
    `product_sku` for first-party services; marketplace product name otherwise.
  </Tab>

  <Tab title="GCP">`sku.id`</Tab>
  <Tab title="Azure">`NULL`</Tab>
  <Tab title="Datadog">`product_name`</Tab>
  <Tab title="Elastic Cloud">Product line **`sku`** code (for example `elasticsearch.general-purpose-search-vcu_gcp-us-central1`).</Tab>
</Tabs>

***

### SKU Description

A human-readable SKU description.

<Tabs>
  <Tab title="AWS">
    `CONCAT(product_operation, "_", product_product_family)` for first-party
    services; marketplace product name otherwise.
  </Tab>

  <Tab title="GCP">`sku.description`</Tab>
  <Tab title="Azure">`meterName`</Tab>
  <Tab title="Datadog">`charge_type`</Tab>
  <Tab title="Elastic Cloud">Same as **Service name** (human-readable product line label).</Tab>
</Tabs>

***

## Location & Infrastructure

### Availability Zone

The availability zone of the resource.

<Tabs>
  <Tab title="AWS">`line_item_availability_zone`</Tab>
  <Tab title="GCP">`location.zone`</Tab>
  <Tab title="Azure">`NULL`</Tab>
  <Tab title="Datadog">`NULL`</Tab>
  <Tab title="Elastic Cloud">`NULL`</Tab>
</Tabs>

***

### Region ID

The raw, provider-specific region identifier.

<Tabs>
  <Tab title="AWS">`product.key_value["region"]` or `product_region_code`</Tab>
  <Tab title="GCP">`location.region`</Tab>
  <Tab title="Azure">`ResourceLocation`</Tab>
  <Tab title="Datadog">`NULL`</Tab>
  <Tab title="Elastic Cloud">Parsed from the product line **SKU** when it includes a cloud/region suffix (for example `gcp-us-central1` from `..._gcp-us-central1`); otherwise `NULL`.</Tab>
</Tabs>

***

### Region

The standardized, human-readable region name. Costory maps each provider's raw region identifier to a common name via an internal region mapper.

<Tabs>
  <Tab title="AWS">`StandardRegionName` joined on `product_region_code`.</Tab>
  <Tab title="GCP">`StandardRegionName` joined on `location.region`.</Tab>
  <Tab title="Azure">`StandardRegionName` joined on `ResourceLocation`.</Tab>
  <Tab title="Datadog">`NULL`</Tab>
  <Tab title="Elastic Cloud">Same **region token** as **Region ID** when present (Elastic encodes region in the SKU string).</Tab>
</Tabs>

***

## Resource

### Resource Id

The unique identifier of the resource.

<Tabs>
  <Tab title="AWS">`line_item_resource_id`</Tab>

  <Tab title="GCP">
    `resource.global_name` (detailed billing only, otherwise `NULL`).
  </Tab>

  <Tab title="Azure">`COALESCE(ResourceId, InstanceId)`</Tab>
  <Tab title="Datadog">`NULL`</Tab>
  <Tab title="Elastic Cloud">Elastic **project id** (same as **Billing account id**).</Tab>
</Tabs>

***

### Resource Name

A human-readable name for the resource.

<Tabs>
  <Tab title="AWS">`line_item_resource_id` (same as Resource Id).</Tab>

  <Tab title="GCP">
    `resource.name` (detailed billing only, otherwise `NULL`).
  </Tab>

  <Tab title="Azure">`COALESCE(ResourceGroupName, ResourceGroup)`</Tab>
  <Tab title="Datadog">`NULL`</Tab>
  <Tab title="Elastic Cloud">Elastic **project name** (same as **Sub account id**).</Tab>
</Tabs>

***

## Commitment Discounts

### Commitment Discount Category

The type of commitment discount. `Usage` indicates a resource-based commitment (Reserved Instances, resource-based CUDs). `Spend` indicates a dollar-based commitment (Savings Plans, dollar-based CUDs).

<Tabs>
  <Tab title="AWS">
    * Savings Plan ARN present becomes **Spend** - Reservation ARN present becomes **Usage**
  </Tab>

  <Tab title="GCP">
    * `COMMITTED_USAGE_DISCOUNT_DOLLAR_BASE` becomes **Spend** -
      `COMMITTED_USAGE_DISCOUNT` becomes **Usage**
  </Tab>

  <Tab title="Azure">
    * `microsoft.capacity` in `benefitId` becomes **Usage** -
      `microsoft.billingbenefits` in `benefitId` becomes **Spend**
  </Tab>

  <Tab title="Datadog">`NULL`</Tab>
  <Tab title="Elastic Cloud">`NULL`</Tab>
</Tabs>

***

### Commitment Discount Id

The identifier of the commitment discount (ARN, CUD name, or benefit ID).

<Tabs>
  <Tab title="AWS">
    `savings_plan_savings_plan_a_r_n` or `reservation_reservation_a_r_n`
  </Tab>

  <Tab title="GCP">`cud.full_name` (extracted from credits array).</Tab>
  <Tab title="Azure">`benefitId`</Tab>
  <Tab title="Datadog">`NULL`</Tab>
  <Tab title="Elastic Cloud">`NULL`</Tab>
</Tabs>

***

## Compute Enrichment

These fields are enriched by Costory to provide deeper visibility into compute spend.

### Machine Type

The instance or machine type (e.g., `m5.xlarge`, `n2-standard-4`).

<Tabs>
  <Tab title="AWS">
    Extracted from `line_item_usage_type` after the `:` separator.
  </Tab>

  <Tab title="GCP">
    From `system_labels` where the key matches `machine_spec`.
  </Tab>

  <Tab title="Azure">
    Extracted from `ProductName` via regex, for Virtual Machines Compute only.
  </Tab>

  <Tab title="Datadog">`NULL`</Tab>
  <Tab title="Elastic Cloud">`NULL`</Tab>
</Tabs>

***

### Machine Family

The machine family (e.g., `m5`, `n2`, `Dv3`).

<Tabs>
  <Tab title="AWS">First part of the machine type (split on `.`).</Tab>

  <Tab title="GCP">
    First part of the `machine_spec` system label (split on `-`).
  </Tab>

  <Tab title="Azure">
    Extracted from `MeterSubCategory` via regex (`Virtual Machines Xxx Series`).
  </Tab>

  <Tab title="Datadog">`NULL`</Tab>
  <Tab title="Elastic Cloud">`NULL`</Tab>
</Tabs>

***

### Pricing Model (Spot / On Demand)

How the resource is priced. Normalized to: `On Demand`, `Spot`, `Reservation`, `Savings Plan`.

<Tabs>
  <Tab title="AWS">
    * `DiscountedUsage` becomes **Reservation** - `SavingsPlanCoveredUsage` becomes
      **Savings Plan** - Usage type contains `SpotUsage` becomes **Spot** - `Usage` becomes
      **On Demand**
  </Tab>

  <Tab title="GCP">
    SKU description contains `Spot` or `Preemptible` becomes **Spot**; otherwise **On
    Demand**.
  </Tab>

  <Tab title="Azure">`NULL`</Tab>
  <Tab title="Datadog">`NULL`</Tab>
  <Tab title="Elastic Cloud">`NULL`</Tab>
</Tabs>

***

### Marketplace Purchase

Whether the charge is a marketplace purchase. This field is not populated directly by billing converters. It is derived downstream by Costory.

***

### Line Item Usage Type

The raw usage type from the provider. Not populated as a `cos_*` column in converters. Available via provider-specific labels (e.g., `aws_line_item_usage_type` for AWS).

<Tabs>
  <Tab title="AWS">`line_item_usage_type`</Tab>
  <Tab title="GCP">SKU description</Tab>
  <Tab title="Azure">`NULL`</Tab>
  <Tab title="Datadog">`NULL`</Tab>
  <Tab title="Elastic Cloud">Line **`type`** on the product line (for example **`VCU`**). Also available on labels such as **`line_type`**.</Tab>
</Tabs>

***

## Kubernetes

These fields provide Kubernetes-level cost attribution. For GCP, most are populated natively from GKE billing labels. For AWS and Azure, they are typically enriched downstream via Costory's K8s integration.

### K8s Cluster Name

The name of the kubernetes cluster.

<Tabs>
  <Tab title="AWS">`NULL` (populated downstream via K8s enrichment).</Tab>
  <Tab title="GCP">Label `k8s-cluster-name`.</Tab>
  <Tab title="Azure">`NULL`</Tab>
  <Tab title="Datadog">`NULL`</Tab>
  <Tab title="Elastic Cloud">`NULL`</Tab>
</Tabs>

***

### K8s Namespace

The kubernetes namespace for that cost.

<Tabs>
  <Tab title="AWS">`NULL`</Tab>
  <Tab title="GCP">Label `k8s-namespace`.</Tab>
  <Tab title="Azure">`NULL`</Tab>
  <Tab title="Datadog">`NULL`</Tab>
  <Tab title="Elastic Cloud">`NULL`</Tab>
</Tabs>

***

### K8s Namespace Reallocated

Namespace reallocated: is a view over namespace with the waste cost reallocated to each namespace depending on their usage: this is only available on AWS EKS.

***

### K8s Workload Name

The name of the workload, it's the name of pod it can contain ids.

<Tabs>
  <Tab title="AWS">`NULL`</Tab>
  <Tab title="GCP">Label `k8s-workload-name`.</Tab>
  <Tab title="Azure">`NULL`</Tab>
  <Tab title="Datadog">`NULL`</Tab>
  <Tab title="Elastic Cloud">`NULL`</Tab>
</Tabs>

***

### K8s Workload Type

The Kubernetes workload type (Deployment, StatefulSet, DaemonSet, etc.).

<Tabs>
  <Tab title="AWS">`NULL`</Tab>
  <Tab title="GCP">Label `k8s-workload-type`.</Tab>
  <Tab title="Azure">`NULL`</Tab>
  <Tab title="Datadog">`NULL`</Tab>
  <Tab title="Elastic Cloud">`NULL`</Tab>
</Tabs>

***

### K8s Node Pool Name

The name of the node pool (node group in AWS).

<Tabs>
  <Tab title="AWS">Resource tag matching `nodegroup_name`.</Tab>
  <Tab title="GCP">Label `k8s-node-pool-name`.</Tab>
  <Tab title="Azure">`NULL`</Tab>
  <Tab title="Datadog">`NULL`</Tab>
  <Tab title="Elastic Cloud">`NULL`</Tab>
</Tabs>


# Alerts
Source: https://docs.costory.io/features/alerts

Monitor cloud spend and custom formulas against a single trigger condition. Build alerts in the UI or through the Costory MCP with the same condition string, then get notified in Slack, Teams, or email.

**Alerts** watch your cost or usage data against one trigger condition and notify you in Slack, Microsoft Teams, or email when it is met.

The alert engine runs on the same query layer as [Explorer](/features/cost-explorer). You define metric rows, write a `condition` expression, and Costory evaluates it on a fixed schedule. The UI and the [Costory MCP](/features/mcp) use the same fields: anything you build in the app, an agent can create with `create_alert`, backtest with `preview_alert`, or list with `list_alerts`.

<Frame>
  <iframe title="Alerts walkthrough" />
</Frame>

## Overview

Each alert has exactly one condition. That keeps evaluation predictable: the same expression you see in the builder is what runs in BigQuery and what the MCP tools accept.

Common uses:

* Catch a service-level spike before it compounds over the billing period
* Monitor one formula across every team or project with a single `groupBy` alert
* Track commitment coverage, marginal cost per user, or any ratio built from multiple metrics
* Get budget threshold notifications without manual spreadsheet checks

<Frame>
  <img alt="Costory alerts page listing active cost alerts" />
</Frame>

## Get started

<Note>
  To create an alert through Claude, describe the outcome: *"alert me on Slack if daily AWS spend goes over \$10k."* The agent builds the queries, backtests the condition, and returns the alert URL. The steps below match what happens in the UI.
</Note>

<Steps>
  <Step title="Open Alerts and create an alert">
    Go to **Alerts** in the Costory app. Click **Create Alert** and pick a pre-built template, or start from a view in [Explorer](/features/cost-explorer).

    <Frame>
      <img alt="Selecting an alert template in Costory" />
    </Frame>

    Common templates include Savings Plan coverage, Kubernetes waste ratio, and weekly cost change alerts.
  </Step>

  <Step title="Build the formula">
    In **Formula**, add one or more metric rows. Each row gets a letter (`a`, `b`, `c`) that you reference in the condition. Use a single row or combine several for ratios and comparisons.

    Pick a trigger preset or write a custom condition. The guided UI compiles presets into the formula string the engine runs.
  </Step>

  <Step title="Set scope and groupBy">
    In **Configuration**, set filters, grouping, aggregation, and currency. If you add a `groupBy` dimension, Costory evaluates the condition independently for every group value. One alert can cover all teams or projects on that dimension.

    When multiple groups breach on the same day, Costory batches them into one notification and keeps the largest breaches for review.
  </Step>

  <Step title="Review the backtest">
    In **Preview**, check the chart and notification preview. The simulator shows when your formula would have fired on historical data before you save. Dimmed markers on the chart indicate days when the condition was met but deduplication prevented a notification.

    <Frame>
      <img alt="7-day rolling relative change alert showing formula, preview chart with alert markers, and notification history" />
    </Frame>
  </Step>

  <Step title="Configure notifications and save">
    Choose Slack, Microsoft Teams, or email recipients. Save the alert. It begins evaluating after the next data refresh.
  </Step>
</Steps>

## Example scenarios

Paste the condition formula into the alert builder, or describe the outcome to Claude and let it call `preview_alert` and `create_alert`.

| Example                    | Description                                                                                                                                                          | Formula                                                                                                                                                      |
| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Weekly spend spike**     | Row `a`: total cloud cost for the scope you monitor. Fires when rolling 7-day spend rises more than 15% vs the prior week. The spend floor reduces low-volume noise. | `(rollingSum(a, 7, DAY) - timeShift(rollingSum(a, 7, DAY), 7, DAY)) / abs(timeShift(rollingSum(a, 7, DAY), 7, DAY)) > 0.15 and rollingSum(a, 7, DAY) > 1000` |
| **Savings Plan coverage**  | Row `a`: Savings Plan covered cost. Row `b`: Savings Plan uncovered cost. Fires when coverage drops below 80%.                                                       | `a / (a + b) < 0.8`                                                                                                                                          |
| **Per-team spend limit**   | Row `a`: cloud cost for the services you monitor. Set `groupBy` to your team dimension in **Configuration**. Fires when any team's daily spend exceeds the cap.      | `a > 5000`                                                                                                                                                   |
| **Daily spend cap**        | Row `a`: total cloud cost for the scope you monitor. Fires when daily spend exceeds a fixed amount.                                                                  | `a > 10000`                                                                                                                                                  |
| **Day-over-day spike**     | Row `a`: total cloud cost for the scope you monitor. Fires when daily spend rises more than 10% vs the previous day.                                                 | `(a - timeShift(a, 1, DAY)) / abs(timeShift(a, 1, DAY)) > 0.1`                                                                                               |
| **Week-over-week jump**    | Row `a`: total cloud cost for the scope you monitor. Fires when spend exceeds the same day last week by more than \$1,000.                                           | `a - timeShift(a, 1, WEEK) > 1000`                                                                                                                           |
| **Marginal cost per user** | Row `a`: infrastructure cost. Row `b`: active users from an [external usage metric](/setup/usage-metrics). Fires when cost per user exceeds \$2.                     | `a / b > 2`                                                                                                                                                  |

## When an alert fires

Notifications go to Slack, Microsoft Teams, or email. Each message includes a **View in Explorer** link pre-filtered to the alert scope, so you can investigate the cost change without rebuilding filters.

<Frame>
  <img alt="Slack notification showing a triggered cost alert grouped by service" />
</Frame>

From the alerts list, you can delete an alert you no longer need. Deleting removes the alert and its history.

## Frequently Asked Questions

<AccordionGroup>
  <Accordion title="Can Claude create and manage alerts for me?">
    Yes. Through the [Costory MCP](/features/mcp), Claude uses `create_alert`, `preview_alert`, and `list_alerts` with the same fields as the UI. Describe the outcome in plain English and the agent handles the queries, condition, and dedup rule.
  </Accordion>

  <Accordion title="How often are alerts evaluated?">
    Costory evaluates alerts every day, or three times a day depending on your plan. Data is checked with at least a 48-hour delay so billing data from your cloud provider is finalized.
  </Accordion>

  <Accordion title="Can I set multiple thresholds on one alert?">
    No. Each alert has one trigger condition. Create separate alerts when you need different thresholds or notification targets.
  </Accordion>

  <Accordion title="What happens when I group by a dimension?">
    Costory evaluates your condition for every value in that dimension. If several groups breach on the same day, you receive one consolidated notification with the largest breaches included.
  </Accordion>

  <Accordion title="Can I alert on custom formulas or ratios?">
    Yes. Add multiple metric rows and write a custom condition, or start from a preset and adjust the compiled formula. Common patterns include Savings Plan coverage ratios and marginal cost per user from [external usage metrics](/setup/usage-metrics).
  </Accordion>

  <Accordion title="Which notification channels does Costory support?">
    Slack, Microsoft Teams, and email. Each notification includes a link to [Explorer](/features/cost-explorer) scoped to the alert.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup>
  <Card title="Costory MCP" icon="robot" href="/features/mcp">
    Query costs and manage alerts from Claude, Cursor, or VS Code
  </Card>

  <Card title="Budgets" icon="money-bill-trend-up" href="/features/budgets">
    Create monthly budgets and configure budget alerts per line
  </Card>

  <Card title="Digest" icon="bolt" href="/features/digest">
    Auto-triage cost anomalies with AI-generated incident reports
  </Card>

  <Card title="Cost Reports" icon="paper-plane" href="/features/slack-reports">
    Send recurring cost snapshots to your team's channels
  </Card>

  <Card title="Explorer" icon="magnifying-glass" href="/features/cost-explorer">
    Drill into specific cost changes with full context
  </Card>

  <Card title="Dimensions" icon="tags" href="/features/tagging/dimensions">
    Create team-level and product-level cost groupings for targeted alerts
  </Card>
</CardGroup>


# Cloud Cost Budgets and Budget Alerts
Source: https://docs.costory.io/features/budgets

Create monthly cloud cost budgets by team, track versions, and trigger Slack or email budget alerts before overruns.

[<Tooltip href="/docs/glossary#budget">Budgets</Tooltip>](/docs/glossary#budget) in Costory give engineering teams monthly cloud cost budgets with built-in budget alerts. Instead of maintaining spreadsheets, you define budget lines by [<Tooltip href="/docs/glossary#dimensions">dimensions</Tooltip>](/features/tagging/dimensions), assign owners, and monitor Budget, Actual, Forecast, and Delta in one place.

<Frame>
  <img alt="Budget preview grid showing monthly values, actual spend, forecast, delta, and owner per virtual dimension value" />
</Frame>

## Cloud cost budgets for engineering teams

Use Budgets when you need clear spend guardrails that map to engineering ownership:

* Replace manual spreadsheet updates with a budget table that tracks Budget, Actual, Forecast, and Delta by line
* Assign owners per budget line to improve [<Tooltip href="/docs/glossary#showback">showback</Tooltip>](/docs/glossary#showback) accountability
* Trigger alerts when actual spend or end-of-month forecast crosses a threshold
* Keep multiple budget versions and compare decisions over time

Budgets are monthly. Each line can have a different owner, so the engineer or manager who controls the spend gets the signal first.

## Set up cloud cost budgets and budget alerts

<Steps>
  <Step title="Create a new budget and choose the scope">
    Open **Budgets** and click **Create a new budget**. In **Setup**, choose the [dimension](/features/tagging/dimensions) that splits costs into budget lines, for example `team`, `business_unit`, or `environment`, set **First month** and **Last month**, and optionally exclude dimension values you do not want in the budget.

    <Frame>
      <img alt="Create budget wizard on the Setup step with virtual dimension and monthly range fields" />
    </Frame>
  </Step>

  <Step title="Choose your budget metric">
    In **Metric**, select the **Currency** and **Cost type** used to evaluate budget performance. Pick the metric your stakeholders already use for monthly reviews.

    <Frame>
      <img alt="Create budget wizard on the Metric step with currency and cost type dropdowns" />
    </Frame>
  </Step>

  <Step title="Choose a fill method">
    In **Fill method**, initialize monthly budget values with one of the available strategies.

    | Fill method        | When to use                                              |
    | ------------------ | -------------------------------------------------------- |
    | Manual             | You already have approved values and want direct control |
    | Import CSV         | Finance prepared values in a spreadsheet                 |
    | Last year + x%     | You want a simple growth model on last year's baseline   |
    | Last x months + y% | You want a moving baseline with growth applied           |

    <Frame>
      <img alt="Create budget wizard on the Fill method step with manual, import CSV, and growth options" />
    </Frame>
  </Step>

  <Step title="Configure, preview, and assign owners">
    After you finish the wizard, review the **Configure & preview** grid. Enter or adjust monthly budget values, then assign an **Owner** per line so alerts and reviews go to the right person.
  </Step>

  <Step title="Configure budget alerts">
    Monitor specific budget lines and add threshold rules. You can alert on:

    * Actual spend exceeds threshold
    * Forecasted end-of-month spend exceeds threshold

    Send alerts by **Email** or **Slack**, and include line owners in notifications for faster escalation.
  </Step>

  <Step title="Save and manage versions">
    Save the configuration as a budget version. When assumptions change, create a new version and keep past versions for historical tracking and auditability.
  </Step>
</Steps>

## Key capabilities for engineering budget workflows

### Monthly budgets by business dimension

Use [dimensions](/features/tagging/dimensions) to structure budgets around how your organization operates. You can budget per team, product, environment, or any business mapping already used in Costory.

### Forecasting with TimesFM

Costory uses **TimesFM by Google** to forecast end-of-month values for each budget line. This helps you escalate risk before an overrun appears in invoiced costs.

### Multi-version tracking

Budgets support version history, so you can:

* Keep the original baseline
* Introduce a revised plan
* Compare past assumptions with current outcomes

### Owner-based accountability

Each budget line can be assigned to a specific owner. This enables practical [showback](/docs/glossary#showback), because teams can see their own target, actual spend, forecast, and delta in one place.

### Budget alerts for faster response

Alert rules reduce manual monitoring overhead. Teams get notified when spend risk appears, then can jump to [Explorer](/features/cost-explorer) to find the root cause and take action.

### Plot budgets alongside actual cost in Explorer and dashboards

You can plot any budget as an area chart directly in [Explorer](/features/cost-explorer). Open the metric selector, switch to the **budget** tab, and pick the budget you want to visualize. Costory renders the budget values per month as a shaded area, so you can see at a glance whether actual spend is tracking above or below target.

<Frame>
  <img alt="Costory dashboard widget editor showing a budget metric with related actual cost grouped by squad" />
</Frame>

Click **Add related cost** in the query bar to automatically add a cost series scoped to the budget's definition. Costory pre-fills the filters and group-by so plotted cost aligns with the budget lines, no manual configuration needed.

You can use the same metric setup inside a [dashboard widget](/features/dashboards#analyze-budget-vs-actual-spend-on-a-dashboard). Edit the widget, add the budget as a metric, click **Add related cost**, and group the related cost by team or squad to analyze actual spend against the overall budget.

## Use cases

### VP Infrastructure review with engineering leads

Track all team budgets in one table and review which lines are on track, at risk, or exceeded before month end.

### Team-level showback

Give each engineering manager clear visibility into their budget line and ownership of follow-up actions.

### Escalation when forecasted spend drifts

Trigger an alert when a forecast crosses a threshold, then investigate the driver in [Explorer](/features/cost-explorer) and coordinate with the line owner.

## Frequently Asked Questions

<AccordionGroup>
  <Accordion title="Are budgets monthly or custom period?">
    Budgets are monthly.
  </Accordion>

  <Accordion title="Can each budget line have a different owner?">
    Yes. Each line can have its own owner for accountability and alert routing.
  </Accordion>

  <Accordion title="How are forecasts generated?">
    Forecasts use TimesFM by Google.
  </Accordion>

  <Accordion title="Can alerts use both actual and forecast conditions?">
    Yes. You can configure rules for actual threshold breaches and forecasted end-of-month threshold breaches.
  </Accordion>

  <Accordion title="Where should I send budget alerts?">
    You can send alerts to Email or Slack. Include budget line owners for faster response.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup>
  <Card title="Dimensions" icon="sitemap" href="/features/tagging/dimensions">
    Build team and business scopes that power budget lines
  </Card>

  <Card title="Explorer" icon="magnifying-glass" href="/features/cost-explorer">
    Investigate the root cause behind a budget drift
  </Card>

  <Card title="Cost Reports" icon="paper-plane" href="/features/slack-reports">
    Share budget progress in weekly or monthly stakeholder updates
  </Card>

  <Card title="Automate Budget Workflow" icon="money-bill-trend-up" href="/use-cases/automate_budget">
    Apply a step-by-step process to roll out budget ownership
  </Card>
</CardGroup>


# Explorer
Source: https://docs.costory.io/features/cost-explorer

Use Costory Explorer to query AWS, GCP, and Azure costs with filters, group-bys, comparison periods, and saved context before turning the result into dashboards, alerts, reports, or MCP prompts.

**Explorer** is the interactive workspace for answering cloud cost questions. Use it when you need to narrow a cost issue with a `Where` clause, group spend by the right dimension, compare periods, and decide what should happen next.

<Frame>
  <img alt="Costory Explorer showing cost breakdown by service with chart and period comparison table" />
</Frame>

## Overview

Explorer is built for investigation. You start with a cost question, refine the query, and use the result as context for another workflow.

Most teams use Explorer to:

* Identify which service, account, region, team, resource, or [dimension](/features/tagging/dimensions) explains a cost change
* Compare the selected period with a reference period to understand absolute and relative movement
* Combine cost metrics, usage metrics, and formulas for unit economics analysis
* Save the query as a dashboard widget, alert, report, or context for the [FinOps MCP](/features/mcp)
* Run the same query over HTTP with the [Query Costs API](/api-reference/queries/overview)

## Build a cost query

The query bar controls what data Explorer returns.

| Control        | What it does                                                                                                                                                                                                          |
| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Metric**     | Select total cost, <Tooltip href="/docs/glossary#contracted-cost">Contracted Cost</Tooltip>, list cost, usage metrics, budgets, or formulas.                                                                          |
| **Group by**   | Break costs down by provider, service, account, region, tag, imported dimension, or [<Tooltip href="/docs/glossary#virtual-dimensions">virtual dimension</Tooltip>](/features/tagging/dimensions#virtual-dimensions). |
| **Date range** | Set the analysis period and aggregation granularity.                                                                                                                                                                  |
| **Compare**    | Add a reference period so each result shows absolute and percentage change.                                                                                                                                           |
| **Where**      | Filter the query to a specific scope. Combine conditions with `AND` or `OR`, or use `Not` to exclude values.                                                                                                          |

<Tip>
  Use **Scopes** in the top toolbar to apply a saved team, environment, or business-unit filter without rebuilding the `Where` clause.
</Tip>

<Tip>
  You can run the same investigation from chat. Ask the [Costory MCP](/features/mcp) something like *"compare this month's GCP spend to last month, grouped by service"* and it queries, compares periods, and suggests the group-by for you.
</Tip>

## What to do with the result

Explorer is often the starting point for a recurring workflow.

<CardGroup>
  <Card title="Create a dashboard" icon="chart-pie" href="/features/dashboards">
    Turn a useful query into a persistent dashboard widget.
  </Card>

  <Card title="Create an alert" icon="bell" href="/features/alerts">
    Monitor the same cost surface and notify owners when a condition is met.
  </Card>

  <Card title="Schedule a Cost Report" icon="paper-plane" href="/features/slack-reports">
    Send a recurring snapshot to Slack, Microsoft Teams, or email.
  </Card>

  <Card title="Continue in MCP" icon="sparkles" href="/features/mcp">
    Copy the query context into Claude, Cursor, VS Code, or Dust through the FinOps MCP.
  </Card>

  <Card title="Query Costs API" icon="code" href="/api-reference/queries/overview">
    Call the same Explorer query from scripts or internal tools over HTTP.
  </Card>
</CardGroup>

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Can I save an Explorer query?">
    Yes. Save the query as a dashboard widget when you want a recurring view, or use it as the basis for an alert or scheduled Cost Report.
  </Accordion>

  <Accordion title="Can I combine costs with business metrics?">
    Yes. Add [usage metrics](/setup/usage-metrics) and formulas in Explorer to calculate ratios such as cost per user or cost per transaction. See [Unit Economics](/features/unit-economics) for the full workflow.
  </Accordion>
</AccordionGroup>

## Related links

<CardGroup>
  <Card title="Dashboards" icon="chart-pie" href="/features/dashboards">
    Build persistent views from Explorer queries.
  </Card>

  <Card title="Unit Economics" icon="calculator" href="/features/unit-economics">
    Add metrics and formulas to cost analysis.
  </Card>

  <Card title="FinOps MCP" icon="sparkles" href="/features/mcp">
    Query Costory data and create FinOps workflows from an AI assistant.
  </Card>

  <Card title="Query Costs API" icon="code" href="/api-reference/queries/overview">
    Run Explorer queries from your own HTTP clients.
  </Card>
</CardGroup>


# Cloud Cost Dashboards
Source: https://docs.costory.io/features/dashboards

Build cloud cost dashboards from Explorer queries to monitor AWS, GCP, and Azure spend, usage metrics, budgets, events, and FinOps KPIs in one place.

**Cloud cost dashboards** turn Explorer queries into persistent views. Use dashboards when an investigation becomes something a team, service owner, finance partner, or executive stakeholder needs to monitor repeatedly.

<Frame>
  <img alt="Costory CTO dashboard with squad breakdown, product line trends, and cost-per-client widgets" />
</Frame>

## Overview

Each dashboard contains one or more widgets. A widget keeps the query context behind it: metric, formula, filters, group-by, selected period, comparison period, and event context.

Use dashboards to:

* Give teams a self-service view of their own spend with <Tooltip href="/docs/glossary#showback">showback</Tooltip> and <Tooltip href="/docs/glossary#chargeback">chargeback</Tooltip> views
* Track executive KPIs such as total spend, top cost drivers, budget progress, and month-over-month movement
* Monitor <Tooltip href="/docs/glossary#savings-plans">Savings Plan</Tooltip> coverage, Kubernetes waste, unit economics, and other FinOps metrics
* Combine cost data with [usage metrics](/setup/usage-metrics) and [events](/features/events) so teams can explain cost changes from the same page

## Dashboard workflows

<Tip>
  You can build a dashboard from chat. Ask the [Costory MCP](/features/mcp) for *"a CTO dashboard with total spend, top services, and month-over-month change"* and it creates the dashboard and widgets, which you can refine in the app.
</Tip>

<CardGroup>
  <Card title="Create and organize dashboards" icon="table-columns" href="/features/dashboards/create-dashboard">
    Create dashboards from Explorer, add widgets manually, and organize dashboards with tags.
  </Card>

  <Card title="Dashboard templates" icon="copy" href="/features/dashboards/templates">
    Start from pre-built FinOps dashboards for executives, teams, commitments, Kubernetes, and network costs.
  </Card>

  <Card title="Widgets and chart types" icon="chart-simple" href="/features/dashboards/widgets">
    Choose bar, line, waterfall, doughnut, table, budget, and KPI widgets for the right analysis.
  </Card>

  <Card title="Quick Share" icon="share-nodes" href="/features/dashboards/quickshare">
    Share a dashboard or widget link for ad-hoc collaboration.
  </Card>
</CardGroup>

## Prerequisites

* At least one cloud provider connected to Costory: [AWS](/setup/billing/aws), [GCP](/setup/billing/gcp), or [Azure](/setup/billing/azure)
* Optional [dimensions](/features/tagging/dimensions) for team, product, environment, or cost-center breakdowns
* Optional [usage metrics](/setup/usage-metrics) for unit economics widgets
* Optional [Teams](/features/teams) for team-owned dashboards and default scopes

## How dashboards relate to Explorer

[Explorer](/features/cost-explorer) is where you investigate a specific question with filters, group-bys, formulas, and comparison periods. Dashboards are where you keep the useful result.

When you save an Explorer query as a dashboard widget, Costory keeps the same query configuration. The widget refreshes as new billing data arrives, so the dashboard stays current without rebuilding the analysis.

## Example dashboard patterns

| Dashboard              | Typical widgets                                                               |
| ---------------------- | ----------------------------------------------------------------------------- |
| Team cost overview     | Cost trend by service, budget progress, top cost drivers, cost per user       |
| Executive overview     | Total spend, month-over-month change, budget vs actual, top teams or products |
| Commitment coverage    | Savings Plan and CUD coverage, uncovered spend, utilization trend             |
| Kubernetes cost review | Namespace cost, workload cost, idle or waste indicators, usage ratios         |
| Migration tracker      | Before-and-after cost trend, event markers, waterfall by service or account   |

For ready-made starting points, see [Dashboard templates](/features/dashboards/templates).

## Sharing and delivery

Dashboards support several sharing workflows:

* Send a direct link to a dashboard for logged-in Costory users.
* Use [Quick Share](/features/dashboards/quickshare) for an ad-hoc public link when you need to share outside the normal Costory workflow.
* Schedule a dashboard snapshot as a [Cost Report](/features/slack-reports) to Slack, Microsoft Teams, or email.
* Assign a dashboard to a [Team](/features/teams) so members see the right dashboards by default.
* Copy the widget SQL for BigQuery workflows when your organization uses [BigQuery Data Exports](/setup/destinations/bigquery).

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Can I create a dashboard from Explorer?">
    Yes. Build the query in [Explorer](/features/cost-explorer), then save it as a dashboard widget. See [Create and organize dashboards](/features/dashboards/create-dashboard) for the steps.
  </Accordion>

  <Accordion title="Can a dashboard include cost and usage metrics together?">
    Yes. Dashboard widgets can use formulas that combine cloud cost with [usage metrics](/setup/usage-metrics), such as cost per active user or cost per build minute.
  </Accordion>

  <Accordion title="Can dashboards be used for chargeback reporting?">
    Yes. Combine [dimensions](/features/tagging/dimensions), [Shared Cost Allocation](/features/tagging/shared-cost-allocation), budget widgets, and scheduled [Cost Reports](/features/slack-reports) to support chargeback workflows.
  </Accordion>

  <Accordion title="How often do dashboards refresh?">
    Dashboards reflect the latest billing data available in Costory. See [Data Refresh](/docs/data-refresh) for ingestion timing.
  </Accordion>
</AccordionGroup>

## Related links

<CardGroup>
  <Card title="Explorer" icon="magnifying-glass" href="/features/cost-explorer">
    Build the queries that power dashboard widgets.
  </Card>

  <Card title="Cost Reports" icon="paper-plane" href="/features/slack-reports">
    Schedule dashboard snapshots to Slack, Teams, or email.
  </Card>

  <Card title="Dimensions" icon="layer-group" href="/features/tagging/dimensions">
    Create team-level and product-level cost groupings.
  </Card>

  <Card title="Budgets" icon="money-bill-trend-up" href="/features/budgets">
    Set spending targets and track progress on dashboards.
  </Card>
</CardGroup>


# Create and Organize Dashboards
Source: https://docs.costory.io/features/dashboards/create-dashboard

Create cloud cost dashboards from Explorer queries, add widgets manually, duplicate widgets, and organize dashboards with tags and teams.

Create dashboards when a cost question becomes a view you want to revisit. A dashboard can start from an [Explorer](/features/cost-explorer) query, a template, or an empty canvas.

## Create a dashboard from Explorer

Use this workflow when an investigation produces a view worth monitoring.

<Steps>
  <Step title="Build the query">
    Open [Explorer](/features/cost-explorer), select the metrics or formulas, apply filters, choose the group-by, and add event context if it helps explain the chart.
  </Step>

  <Step title="Save as a dashboard">
    Click **Save as dashboard** and choose whether to create a new dashboard or add the view to an existing dashboard.
  </Step>

  <Step title="Adjust the widget">
    Rename the widget, choose the visualization, and place it next to related widgets.
  </Step>

  <Step title="Save the dashboard">
    The widget keeps the Explorer query and refreshes as new billing data arrives.
  </Step>
</Steps>

<Tip>
  If you are starting from a common FinOps workflow, use a [dashboard template](/features/dashboards/templates) instead of building each widget manually.
</Tip>

<Tip>
  Skip the canvas entirely: ask the [Costory MCP](/features/mcp) to *"create a dashboard tracking cost per team with a budget widget"* and it builds the widgets for you to review.
</Tip>

## Add a widget manually

Use manual widgets when you already know the metric, grouping, and chart you want.

<Frame>
  <img alt="Adding a widget manually to a Costory dashboard" />
</Frame>

<Steps>
  <Step title="Open a dashboard">
    Navigate to an existing dashboard or create a new one.
  </Step>

  <Step title="Add a widget">
    Click **Add Widget** and choose a widget type.
  </Step>

  <Step title="Configure the query">
    Select the cost metric, filters, group-by, and visualization. You can use any dimension available in Explorer, including [dimensions](/features/tagging/dimensions) and custom formulas.
  </Step>

  <Step title="Save the widget">
    Click **Save**. The widget updates after each data refresh.
  </Step>
</Steps>

For chart options, see [Widgets and chart types](/features/dashboards/widgets).

## Duplicate a widget

Duplicate widgets when you need the same chart structure with a different filter. For example, duplicate a cost trend widget and swap the team filter to create the same view for another team.

<Frame>
  <img alt="Dashboard action menu showing the option to duplicate a widget in Costory" />
</Frame>

## Organize dashboards with tags

Use dashboard tags to group dashboards by team, workflow, reporting cadence, or FinOps process. Tags appear on the **View all dashboards** page.

<Frame>
  <img alt="Dashboard tags on the View all dashboards page" />
</Frame>

<Steps>
  <Step title="Open all dashboards">
    Navigate to **Dashboards** and click **View all dashboards**.
  </Step>

  <Step title="Select dashboards">
    Select one or more dashboards you want to tag.
  </Step>

  <Step title="Edit tags">
    Click **Edit tags**, add the tags you want, and remove tags that no longer apply.
  </Step>

  <Step title="Save the changes">
    Save the tag changes. The dashboard list updates with the new tags.
  </Step>
</Steps>

Dashboard tags organize dashboards only. They do not change widget filters, team scopes, or [dimensions](/features/tagging/dimensions).

## Assign dashboards to teams

Assign dashboards to a [Team](/features/teams) when a dashboard belongs to a specific group. Team dashboards appear by default for team members, and private dashboards are restricted to team members.

This is useful for:

* Team showback dashboards
* Product-line dashboards
* Budget owner dashboards
* Platform or SRE dashboards

## Related links

<CardGroup>
  <Card title="Dashboard templates" icon="copy" href="/features/dashboards/templates">
    Start from common FinOps dashboard layouts.
  </Card>

  <Card title="Widgets and chart types" icon="chart-simple" href="/features/dashboards/widgets">
    Choose the right widget for each cost question.
  </Card>

  <Card title="Quick Share" icon="share-nodes" href="/features/dashboards/quickshare">
    Share dashboard context with teammates or external collaborators.
  </Card>

  <Card title="Cost Reports" icon="paper-plane" href="/features/slack-reports">
    Deliver dashboards to Slack, Teams, or email on a schedule.
  </Card>
</CardGroup>


# Quick Share
Source: https://docs.costory.io/features/dashboards/quickshare

Share a Costory dashboard or dashboard widget with a public link for ad-hoc cloud cost collaboration in Slack, Microsoft Teams, pull requests, or incident threads.

**Quick Share** creates a link for ad-hoc collaboration around a dashboard or dashboard widget. Use it when someone needs to see the exact cost context behind a discussion without building the dashboard in their own workspace.

<Frame>
  <img alt="Quick Share panel for sharing Costory cost context with a link" />
</Frame>

## When to use Quick Share

Use Quick Share for short-lived collaboration:

* Send a dashboard widget to a teammate during a cost investigation
* Add cost context to a Slack or Microsoft Teams thread
* Link the cost impact of a change in a pull request
* Hand off a dashboard view to an on-call engineer during incident triage
* Share a budget or migration review snapshot with stakeholders who do not need recurring delivery

For recurring delivery, use [Cost Reports](/features/slack-reports). For ongoing monitoring, keep the view on a [dashboard](/features/dashboards).

## Share dashboard context

<Steps>
  <Step title="Open the dashboard">
    Navigate to the dashboard or widget you want to share.
  </Step>

  <Step title="Review the context">
    Confirm the dashboard filters, widget filters, date range, comparison period, and event context are safe to share.
  </Step>

  <Step title="Generate the link">
    Click **Quick Share** or use the sharing action from the widget menu.
  </Step>

  <Step title="Send the link">
    Paste the link in Slack, Microsoft Teams, a pull request, an incident thread, or email.
  </Step>
</Steps>

<Frame>
  <img alt="Generating a Quick Share link for Costory cost context" />
</Frame>

The shared link is read-only. Recipients can review the cost context without changing the original dashboard or widget.

## Quick Share compared with other sharing options

| Method                                  | Best for                                                          |
| --------------------------------------- | ----------------------------------------------------------------- |
| Quick Share                             | Short-lived collaboration around a dashboard or widget            |
| Dashboard URL                           | Internal Costory users who need ongoing access                    |
| [Cost Reports](/features/slack-reports) | Recurring snapshots to Slack, Microsoft Teams, or email           |
| [Digest](/features/digest)              | Automated cost-change summaries and AI-generated incident reports |

## Security and privacy

Quick Share links are publicly accessible URLs. Anyone with the link can view the shared cost context without logging in to Costory.

<Warning>
  Review the dashboard or widget before sharing. Viewers see the cost data according to your permissions at the time you create the link.
</Warning>

* Shared links expire after 90 days.
* Recipients cannot modify the original dashboard or widget.
* Treat shared links like public document links.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Can I share a link with someone outside my organization?">
    Yes. Quick Share links are publicly accessible, so anyone with the URL can view the shared cost context until the link expires.
  </Accordion>

  <Accordion title="Does modifying a shared view affect the original dashboard?">
    No. Quick Share is read-only for recipients and does not modify the original dashboard or widget.
  </Accordion>

  <Accordion title="Can I revoke a shared link?">
    Shared links cannot be revoked manually today. They expire automatically after 90 days. If you shared sensitive data by mistake, contact support.
  </Accordion>
</AccordionGroup>

## Related links

<CardGroup>
  <Card title="Dashboards" icon="chart-pie" href="/features/dashboards">
    Build the dashboard or widget you want to share.
  </Card>

  <Card title="Create and organize dashboards" icon="table-columns" href="/features/dashboards/create-dashboard">
    Create dashboards from Explorer or an empty canvas.
  </Card>

  <Card title="Cost Reports" icon="paper-plane" href="/features/slack-reports">
    Schedule recurring cost snapshots to Slack, Teams, or email.
  </Card>

  <Card title="Digest" icon="bolt" href="/features/digest">
    Share automated cost-change analysis.
  </Card>
</CardGroup>


# Dashboard Templates
Source: https://docs.costory.io/features/dashboards/templates

Use pre-built FinOps dashboard templates for executive cloud cost reporting, team showback, Savings Plan coverage, Kubernetes cost allocation, network costs, and storage optimization.

Dashboard templates give you a starting point for common FinOps workflows. Each template creates a dashboard with preconfigured widgets, filters, group-bys, and comparison periods that use your connected billing data.

<Frame>
  <img alt="Costory dashboard library with a selected CTO dashboard and dashboard widget preview" />
</Frame>

## When to use templates

Use a template when you want a working dashboard without deciding every widget first. After creating the dashboard, edit any widget to change the metric, chart type, filter, group-by, or date range.

Templates are useful for:

* Creating a repeatable dashboard for each team or product line
* Starting a monthly cost review without rebuilding the same charts
* Monitoring commitment coverage, Kubernetes costs, or network costs with standard FinOps views
* Giving executives a concise page with top cost drivers and budget movement

## Available templates

| Template                      | What it tracks                                                                                                                                     |
| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| CTO / Executive overview      | Total spend trend, top cost drivers, budget progress, and month-over-month comparison                                                              |
| Team cost overview            | Per-team spend scoped by [dimensions](/features/tagging/dimensions), service breakdown, budget progress, and cost efficiency metrics               |
| Savings Plan and CUD coverage | Covered vs uncovered spend, utilization rate, and coverage trend for commitment planning                                                           |
| Kubernetes cost breakdown     | Cost by cluster, namespace, workload, and waste indicator. See [EKS cost allocation](/use-cases/eks-cost-allocation).                              |
| Network cost analysis         | Cross-AZ, egress, and transfer cost drivers by provider, service, account, or team                                                                 |
| BigQuery cost attribution     | BigQuery spend by project, dbt model, package, or team. See [BigQuery and dbt visibility](/use-cases/dbt_bigquery_visibility/increase_visibility). |
| Storage cost optimization     | Unattached volumes, underused disks, backup growth, and high-cost storage classes                                                                  |

## Create a dashboard from a template

<Steps>
  <Step title="Open Dashboards">
    Navigate to **Dashboards**.
  </Step>

  <Step title="Create a dashboard">
    Click **Create Dashboard**.
  </Step>

  <Step title="Choose a template">
    Select the template that matches your workflow.
  </Step>

  <Step title="Review the generated dashboard">
    Costory creates the dashboard with widgets populated from your connected billing data.
  </Step>

  <Step title="Customize widgets">
    Edit filters, group-bys, chart types, date ranges, and labels so the dashboard matches your organization.
  </Step>
</Steps>

## Apply team scopes

Team templates work best when your [dimensions](/features/tagging/dimensions) already map cloud resources to owners. Create one team dashboard, verify the layout, then duplicate it and swap the team filter for each additional team.

You can also use [Teams](/features/teams) to assign dashboards to team members and apply default scopes.

## Template follow-ups

After you create a template dashboard, you can:

* Add or replace widgets with [dashboard widgets](/features/dashboards/widgets)
* Send a public link with [Quick Share](/features/dashboards/quickshare)
* Schedule the dashboard as a [Cost Report](/features/slack-reports)
* Create an [alert](/features/alerts) from the same query logic when a KPI needs monitoring

## Related links

<CardGroup>
  <Card title="Create and organize dashboards" icon="table-columns" href="/features/dashboards/create-dashboard">
    Build dashboards from Explorer or an empty canvas.
  </Card>

  <Card title="Widgets and chart types" icon="chart-simple" href="/features/dashboards/widgets">
    Customize the widgets created by a template.
  </Card>

  <Card title="Dimensions" icon="layer-group" href="/features/tagging/dimensions">
    Configure team, product, or environment groupings before using team templates.
  </Card>

  <Card title="Kubernetes Cost Visibility" icon="dharmachakra" href="/use-cases/eks-cost-allocation">
    Break down Kubernetes costs by namespace, workload, and pod.
  </Card>
</CardGroup>


# Dashboard Widgets and Chart Types
Source: https://docs.costory.io/features/dashboards/widgets

Choose dashboard widgets and chart types for cloud cost dashboards, including bar charts, line charts, waterfall charts, doughnut charts, tables, KPI cards, budget trackers, and BigQuery SQL export.

Dashboard widgets are saved cost views. Each widget can use Explorer-style metrics, formulas, filters, group-bys, comparison periods, and event context.

## Widget types

| Widget         | Best for                                                                                        |
| -------------- | ----------------------------------------------------------------------------------------------- |
| Cost trend     | Showing spend over time with a line, area, or bar chart                                         |
| Cost breakdown | Showing how groups contribute to total spend by service, account, team, product, or environment |
| Waterfall      | Explaining which groups drove an increase or decrease between two periods                       |
| Doughnut       | Showing the proportional split of a selected period                                             |
| Table          | Reviewing sortable cost data and exact values                                                   |
| KPI card       | Displaying one number, such as total spend, cost per user, or Savings Plan coverage             |
| Budget tracker | Comparing actual spend with a [budget](/features/budgets) target                                |

## Chart types

Choose the chart type based on the question the widget should answer.

<Frame>
  <img alt="Chart type selector showing Line, Bar, Donut, Waterfall, and Table visualization options in Costory" />
</Frame>

| Chart type      | Use it when                                                                                  |
| --------------- | -------------------------------------------------------------------------------------------- |
| Bar chart       | You need to compare grouped spend over time and see how each group contributes to the total. |
| Line chart      | You need to compare trends across services, teams, or providers.                             |
| Area chart      | You need a trend view that emphasizes total spend volume.                                    |
| Doughnut chart  | You need a proportional split for one period, such as spend by provider or team.             |
| Waterfall chart | You need to explain what changed between the selected period and the reference period.       |
| Table           | You need exact values, sorting, or a top-cost breakdown.                                     |

## Waterfall charts

Waterfall charts show which services, accounts, teams, or products drove a cost increase or decrease between two periods. Use them during budget reviews, migration reviews, and cost-change explanations.

<Frame>
  <img alt="Cost Waterfall chart breaking down an AWS cost increase by service" />
</Frame>

Pair waterfall charts with [events](/features/events) when you need to explain whether a deploy, migration, purchase, or business change happened near the cost movement.

## Doughnut charts

Doughnut charts show proportional spend for a selected period. Use them for high-level split views such as cost by provider, business unit, environment, or product.

## Tables

Table widgets show the data behind a chart. Use them when reviewers need exact values, sorting, or exportable cost breakdowns.

Open the **Display** menu on a table to control sort field and direction, hide empty rows, limit the list with **Top N**, show a **Total** column, and set decimal **Precision**. These options change how the table is shown, not the underlying query.

<Frame>
  <img alt="Table widget Display menu with sort, hide empty rows, Top N, show total, and precision options" />
</Frame>

Tables can include:

* Selected-period cost
* Reference-period cost when comparison is enabled
* Absolute change
* Relative change
* Cost, usage, budget, or formula values

## Budget vs actual widgets

Use a budget widget when you want to compare an approved [<Tooltip href="/docs/glossary#budget">budget</Tooltip>](/features/budgets) with actual spend.

<Steps>
  <Step title="Edit the dashboard widget">
    Open the dashboard, click the widget action menu, and select **Edit widget**.
  </Step>

  <Step title="Add the budget metric">
    Click **Add Metric**, open the **budget** tab, and choose the budget version you want to analyze.
  </Step>

  <Step title="Add related cost">
    Open the action menu for the budget metric and click **Add related cost**. Costory adds a cost metric scoped to the budget definition.
  </Step>

  <Step title="Break actual spend down">
    Set **Group By** on the related cost metric to the dimension you use for ownership, such as team, squad, or product line.
  </Step>

  <Step title="Save the widget">
    Click **Save**.
  </Step>
</Steps>

<Frame>
  <img alt="Costory dashboard widget editor showing a budget metric with related actual cost grouped by squad" />
</Frame>

## Color palettes

Each chart widget can use one of four color palettes. Switch palettes to keep visuals readable across stacked bars, line charts, and grouped breakdowns. The setting lives in the widget editor's chart display options.

<Frame>
  <img alt="Chart color palette options in a dashboard" />
</Frame>

## Export widget SQL to BigQuery

BigQuery data exports let you query the same cost data shown in a dashboard widget from your own BigQuery project. Use this when you want to reuse dashboard logic in Looker, notebooks, dbt, or custom SQL without rebuilding filters.

<Frame>
  <img alt="Copy SQL query action on a dashboard widget" />
</Frame>

<Steps>
  <Step title="Set up the BigQuery destination">
    Ask an **Organization Admin** to grant your BigQuery user or service account read access to the Costory export table under **Integrations > Destinations**. See [BigQuery Data Exports](/setup/destinations/bigquery) for setup.
  </Step>

  <Step title="Open the dashboard widget">
    Open the dashboard that contains the widget you want to query outside Costory.
  </Step>

  <Step title="Copy the SQL">
    Open the widget action menu and click **Copy SQL query**.
  </Step>

  <Step title="Run the query">
    Paste the SQL into BigQuery, Looker, or a notebook that can query BigQuery.
  </Step>
</Steps>

The copied SQL reflects the widget configuration, including metric, filters, group-by, and date range.

## Related links

<CardGroup>
  <Card title="Create and organize dashboards" icon="table-columns" href="/features/dashboards/create-dashboard">
    Add widgets to dashboards and organize them for teams.
  </Card>

  <Card title="Dashboard templates" icon="copy" href="/features/dashboards/templates">
    Start with pre-built FinOps widgets.
  </Card>

  <Card title="Unit Economics" icon="calculator" href="/features/unit-economics">
    Add usage metrics and formulas to the queries behind widgets.
  </Card>

  <Card title="BigQuery Data Exports" icon="database" href="/setup/destinations/bigquery">
    Set up the destination used by SQL export.
  </Card>
</CardGroup>


# Cost Digest: automate your FinOps reporting
Source: https://docs.costory.io/features/digest

Automatically surface and triage the cloud cost changes that matter for FinOps reporting. Digest ranks every significant cost shift by dollar impact and generates AI incident reports with root cause analysis.

Cloud bills contain millions of line items with no sense of priority. **Digest** surfaces only the cost changes that matter, ranked by real dollar impact, with AI-generated explanations for each one.

Monthly cloud cost reviews stall when you have to dig through your different billing consoles, GitHub PRs, and incidents. **Cost digest** ranks the changes that moved the bill, explains them with AI, and ships the result inside a scheduled [Cost Report](/v2/Automate/reports).

<iframe title="Cost digest walkthrough" />

## What is a cloud cost digest

A **cloud cost digest** is an automated FinOps report that compares one billing period to another, ranks the largest cost movers by dollar impact, and drafts a plain-language explanation of why spend changed. Platform engineers use it to replace the monthly write-up they would otherwise assemble from billing consoles, GitHub PRs, and incident history. Finance and engineering stakeholders get a shareable Summary they can read without a dashboard walkthrough.

A static chart or a table of numbers only shows that spend moved. Digest adds the ranked drivers and optional AI root-cause analysis, then delivers the narrative to Slack or email on a schedule. Digests cover AWS, GCP, Azure, and AI spend in the same tree.

## Automate FinOps reporting with Digest

Digest is an element inside a [Cost Report](/v2/Automate/reports), not a standalone export. You set the report scope once (metric, group-by, filters, currency), add a **Cost digest**, and stack other elements around it to match how you already report: a **Graph** for the trend, **Text** for markdown context, **Top / Flop** for a short ranking, or a **Dashboard PDF** when stakeholders still want the full board. Inside Costory you can reopen each run as **Summary**, **Tree**, or **Table**.

Where FinOps reporting usually breaks down without a digest:

* Pasting screenshots into Notion or Slack and answering "what happened?" in thread. See the [monthly reporting guide](/automate-reporting/monthly-reviews).
* Shipping charts without an explanation, so finance still needs a live walkthrough
* Leaving each engineering squad without a scoped view of their own movers. Use [dimensions](/features/tagging/dimensions) to filter digests per team
* Rebuilding a spreadsheet when an alert fires or a CFO asks why the bill jumped

## Key terms used in this article

* **Cost digest**: A report element that turns period-over-period cost changes into a ranked tree and optional AI narrative for FinOps reporting.
* **Report parameters**: The shared scope for every element in the report: **Metric**, **Group By**, **Where**, and **Currency**.
* **Additional group by**: Extra dimensions stacked under the report **Group By**, in order. Each one adds a deeper level to the tree.
* **AI investigation**: An async analysis that runs after scheduled or manual delivery. Deepest leaf nodes get root-cause text. It does not appear in the builder preview.
* **Costory AI**: Costory's AI FinOps assistant. It drafts the digest narrative and per-node explanations.

See the [Glossary](/docs/glossary) for a full list of terms.

## Prerequisites

* Cloud billing data connected for AWS, GCP, Azure, or your other sources. Start with the [Quickstart](/get-started/quickstart).
* For Slack or email delivery, finish [Slack](/setup/collaboration/slack) or [Email](/setup/collaboration/email) setup.
* Optional: connect [events](/setup/events) so AI explanations can reference deploys, incidents, or pricing changes.

## Get started

<Tip>
  You can build the same digest from chat. Ask the [Costory MCP](/features/mcp) to *"send a monthly cost digest grouped by provider then service to #finops with AI investigation on"* and it creates the report for you.
</Tip>

<Steps>
  <Step title="Create or open a Cost Report">
    Go to **Reports** and create a report, or open an existing one. Set the shared parameters that every element inherits.

    <ResponseField name="Metric">
      Usually **Cost**.
    </ResponseField>

    <ResponseField name="Group By">
      The first level of the digest tree, for example **Provider**, environment, or team.
    </ResponseField>

    <ResponseField name="Where">
      Optional filters. Example: one condition to exclude marketplace spend.
    </ResponseField>

    <ResponseField name="Currency">
      Display currency for the report, such as **USD \$**.
    </ResponseField>
  </Step>

  <Step title="Add and configure a Cost digest element">
    Click **+ Add Element** and choose **Cost digest**. Stack dimensions under **Additional group by** in the order you want the tree to expand. Tune thresholds and turn on AI investigation when you want narratives after delivery.

    <Frame>
      <img alt="Cost digest element settings showing Environment and Service Name additional group by, thresholds, and AI investigation enabled" />
    </Frame>

    <ResponseField name="Additional group by (order matters)">
      Extra levels under the report **Group By**. Example: Environment, then Service Name.
    </ResponseField>

    <ResponseField name="Top largest absolute change" type="5 | 10 | 15 | 20 | 30 | 50">
      How many largest absolute movers to surface. Default: `10`.
    </ResponseField>

    <ResponseField name="Min absolute diff" type="number">
      Hide nodes whose absolute change is below this value. Default: `100`.
    </ResponseField>

    <ResponseField name="Min relative diff (%)" type="number">
      Hide nodes whose percentage change is below this threshold. Default: `5`.
    </ResponseField>

    <ResponseField name="Enable AI investigation" type="boolean">
      When on, deepest leaf nodes get an async AI investigation after scheduled or manual delivery. Not available in the builder preview.
    </ResponseField>

    <ResponseField name="Comparison">
      The reference period shown against the current period, for example last full month vs the previous month.
    </ResponseField>

    Other element types you can mix in the same report: **Top / Flop**, **Graph**, **Dashboard PDF**, and **Text** (markdown edited in the preview).
  </Step>

  <Step title="Preview as Tree or Table">
    Use **Display** in the preview to switch between **Tree** and **Table** while you tune dimensions and thresholds. **Show** filters increases, decreases, or all nodes.
  </Step>

  <Step title="Schedule delivery to Slack or email">
    Open **Schedule & send**, turn on **Recurring report**, pick a cadence, and add destinations. Put channels or emails that share the same filters in one row so the report runs once and fans out. Use separate rows for different filters or delivery types.

    <Frame>
      <img alt="Costory Schedule and send panel with recurring monthly report and email destination" />
    </Frame>

    <Info>
      AI investigation runs after delivery. Recipients see the narrative once the investigation finishes. **Test send** still validates destinations and layout.
    </Info>
  </Step>
</Steps>

## How to read a Cost digest

### Tree

**Tree** is the hierarchical breakdown: provider, then your additional dimensions, with absolute change, percentage change, and previous-to-current amounts. Increases show in red, decreases in green.

<Frame>
  <img alt="Cost digest Tree view in the report builder for AWS and DataDog cost changes" />
</Frame>

### Table

**Table** flattens the same nodes into columns such as Provider, Environment, Service Name, Absolute diff, and Relative diff. Useful when you want to scan or export movers without expanding the tree.

<Frame>
  <img alt="Cost digest Table view listing provider, environment, and service cost changes" />
</Frame>

### Summary

After a run with **Enable AI investigation** on, open the sent digest and switch **Display** to **Summary** for the AI narrative. That narrative is what Slack and email recipients typically receive.

## Build digests with the API or MCP

The UI, [Costory MCP](/features/mcp), and [Reports API](/api-reference/reports/overview) create the same `DIGEST` widget. Example: weekly engineering pulse grouped by environment, then service, with AI investigation on.

```json theme={null}
POST /reports
{
  "name": "Weekly engineering pulse",
  "scheduledPeriod": "WEEKLY",
  "scheduledWeekday": 1,
  "context": { "groupBy": "env", "datePreset": "LAST_WEEK" },
  "widgets": [
    {
      "type": "DIGEST",
      "enableAiInvestigation": true,
      "additionalGroupBy": ["cos_service_name"],
      "topLargestAbsoluteChange": 20,
      "minAbsoluteDiff": 100,
      "minRelativeDiff": 5,
      "advancedExplorerRequest": {
        "period": { "datePreset": "LAST_WEEK", "aggBy": "Week" },
        "queries": [
          {
            "type": "cost",
            "metricId": "cost",
            "aggregator": "SUM",
            "groupBy": "env",
            "whereClause": {},
            "name": "Cost",
            "colorIndex": 0,
            "chartType": "TABLE"
          }
        ],
        "eventsFilter": {},
        "bookmarkedEvents": []
      }
    }
  ],
  "destinations": [
    { "destinationType": "SLACK", "destinationValue": "C0ENGCOSTS" }
  ]
}
```

See [Create a report](/api-reference/reports/create-a-report) for the full schema. A `table` DIGEST supports at most two group-by dimensions (report `context.groupBy` plus `additionalGroupBy`).

## FinOps use cases

### Automate monthly FinOps reporting

Set **Group By** to Provider, add Environment then Service Name as additional dimensions, enable AI investigation, and schedule monthly email to finance. You stop assembling the monthly write-up by hand. Finance gets the Summary narrative; you keep the Tree when someone asks for detail. Walkthrough: [Automate Monthly Cloud Cost Reporting](/automate-reporting/monthly-reviews).

### Squad cost ownership

Filter **Where** to one team dimension, group by service, and send weekly Slack digests to each squad channel. Engineers see their own movers first, so fewer "is this ours?" pings land on the platform team. See [Decentralize FinOps](/automate-reporting/decentralize-finops).

### Cloud cost root cause on demand

Leave scheduling off, add a Cost digest with AI investigation, and [run the report now](/api-reference/reports/run-a-report-now) when an alert fires or a CFO asks why the bill jumped. The digest ranks which services or projects drove the change and drafts the explanation in the same shape you would write yourself.

## Frequently Asked Questions

<AccordionGroup>
  <Accordion title="What is Costory Digest?">
    Costory Digest is a FinOps reporting element that ranks period-over-period cloud cost changes by dollar impact and generates AI explanations for the movers. You add it to a [Cost Report](/v2/Automate/reports), optionally stack charts or markdown around it, and schedule delivery to Slack or email.
  </Accordion>

  <Accordion title="How is a Cost digest different from a static cost chart?">
    A chart shows that spend moved. A Cost digest ranks the drivers across dimensions you choose, applies absolute and relative thresholds, and can attach an AI narrative with root-cause analysis. Recipients get the explanation, not only the numbers.
  </Accordion>

  <Accordion title="Is Digest still a separate product area?">
    Cost digest lives inside [Cost Reports](/v2/Automate/reports). You build it as an element next to graphs, Top / Flop, dashboard PDFs, and text. Older standalone digest flows map to the same tree and AI behavior inside reports.
  </Accordion>

  <Accordion title="Why is the AI text missing in the builder preview?">
    **Enable AI investigation** runs after scheduled or manual delivery. The builder preview shows structure and thresholds only. Open a sent run and switch to **Summary** or expand Tree leaves to read the narrative.
  </Accordion>

  <Accordion title="How do I choose digest dimensions?">
    Start with report **Group By** for the first level. Use **Additional group by** for deeper levels, in the order you want the tree to expand. Common stacks: Provider then Service Name, Team then Project, or Environment then Service Name.
  </Accordion>

  <Accordion title="Does Cost digest work across AWS, GCP, and Azure?">
    Yes. Digests use all connected providers. Put Provider at the top of the tree, or group cross-cloud by team, environment, or any other [dimension](/features/tagging/dimensions).
  </Accordion>

  <Accordion title="What is the difference between Cost digest and Top / Flop?">
    **Top / Flop** lists the largest increases and decreases for a single group-by. **Cost digest** builds a multi-level tree, applies absolute and relative thresholds, and can attach an AI narrative for Slack, email, and in-app Summary or Tree views.
  </Accordion>

  <Accordion title="Can I mix a digest with other report elements?">
    Yes. A common monthly pack is Text (context), Graph (trend), and Cost digest (drivers). Configure them once, then schedule to Slack, Teams, or email.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup>
  <Card title="Cost Reports" icon="paper-plane" href="/v2/Automate/reports">
    Build reports from parameters, elements, schedule, and destinations
  </Card>

  <Card title="Automate Monthly Reporting" icon="calendar" href="/automate-reporting/monthly-reviews">
    Replace manual monthly cost reviews with digests
  </Card>

  <Card title="Reports API" icon="code" href="/api-reference/reports/overview">
    Create DIGEST widgets over HTTP
  </Card>

  <Card title="Explorer" icon="magnifying-glass" href="/features/cost-explorer">
    Drill into a cost change with full query context
  </Card>

  <Card title="Decentralize FinOps" icon="users" href="/automate-reporting/decentralize-finops">
    Give each squad a scoped digest
  </Card>

  <Card title="Executive Cost Reports" icon="chart-line" href="/use-cases/what_your_exec_team_wants/value">
    Package digests for leadership
  </Card>
</CardGroup>


# Events
Source: https://docs.costory.io/features/events

Overlay deploy events, Savings Plan purchases, provider changes, and saved business context on Costory cost charts to explain cloud cost changes.

Events add context to cost data. They capture deployments, releases, incidents, provider changes, and business milestones so you can explain why spend changed without switching between billing tools and engineering systems.

<Frame>
  <img alt="Adding event context to dashboard widgets so cost changes can be explained from the chart" />
</Frame>

## Overview

<Tooltip href="/docs/glossary#event-correlation">Event correlation</Tooltip> overlays events directly on your cost charts. You can compare deploys, purchases, incidents, and custom business events with the spend line in [Explorer](/features/cost-explorer), then save that context to dashboards and reports.

Use events when you need to:

* Save the context behind a cost change
* Correlate deploys, incidents, commitment purchases, and provider changes with spend
* Attach event context to Explorer views, dashboards, and reports
* Give finance and engineering the same timeline for cost discussions

## When to use event correlation

* EC2 spend increases after a deploy marker. Open the event to see which PR was merged and what changed.
* A <Tooltip href="/docs/glossary#savings-plans">Savings Plan</Tooltip> purchase appears on the chart. Verify whether the cost line drops as expected in the following days.
* A dashboard widget needs context before you share it with another team. Attach the relevant event overlay so the viewer sees the cost movement and the reason together.
* A cost anomaly starts near an outage, migration, campaign, or infrastructure change. Use event markers to rule in or rule out likely causes.

<Frame>
  <img alt="Cost chart where deploy and purchase event markers align with cost changes" />
</Frame>

## Use events in Explorer

<Steps>
  <Step title="Open Explorer">
    Navigate to [Explorer](/features/cost-explorer) and build the cost query you want to explain.
  </Step>

  <Step title="Enable event overlays">
    Click **Show Events** in the toolbar. The Events panel opens with available events grouped by category. Toggle categories on or off, or add individual events to the chart.
  </Step>

  <Step title="Investigate a cost change">
    Event markers appear as numbered badges on the chart timeline. Hover over a marker to see the event type, timestamp, and description.

    <Frame>
      <img alt="Cost chart where a numbered deploy marker aligns with a cost increase" />
    </Frame>
  </Step>

  <Step title="Save the context">
    Save the Explorer view, add it to a [dashboard](/features/dashboards), or schedule it as a [Cost Report](/features/slack-reports) so the event context stays attached.
  </Step>
</Steps>

<Tip>
  Pair events with [waterfall charts](/features/dashboards/widgets#waterfall-charts). The waterfall shows which services or teams moved. Events help explain what changed around the same date.
</Tip>

## Example: investigate a cost spike after a deploy

Your weekly EC2 bill increases by 30% starting March 5. Event correlation helps you move from cost movement to likely cause:

1. Open Explorer and filter to EC2 costs for the past two weeks.
2. Enable GitHub events. A deploy marker appears on March 5, the same day the spike starts.
3. Open the event details. PR #1234 was merged with the description "Add nightly batch processing job for ML model retraining."
4. Use the event context to decide whether to optimize instance types, adjust scheduling, or accept the added cost.

Without events, the same investigation usually requires checking deployment logs, Slack threads, CI/CD history, and billing data separately.

## Attach events to dashboards and reports

You can attach event overlays to dashboard widgets so the context travels with the data. When a colleague opens the dashboard or receives it as a Cost Report, they see both the cost data and the events that explain it.

<Frame>
  <img alt="Costory dashboard contextualized with events on cost charts" />
</Frame>

<Tip>
  For automated cost change detection, the [Digest](/features/digest) surfaces high-impact changes and generates AI summaries you can share.
</Tip>

## Find and manage saved events

The Events page is where you search, filter, create, and reopen events across your organization. Each saved event can include the date, source, category, labels, description, and linked cost analysis.

<Frame>
  <img alt="Central Events page showing deploy events, Savings Plan purchases, and custom events filterable by source and tag" />
</Frame>

From the Events page, you can:

* Search by title, source, category, label, or date range
* Open an event to review its description and linked context
* Add an event to an Explorer chart
* Edit manually created events when the context changes

## Create a saved event with context

<Tip>
  You can log an event from chat. Tell the [Costory MCP](/features/mcp) *"add a deploy event for the payments service today"* and it creates the annotation so it shows up on your cost charts.
</Tip>

<Steps>
  <Step title="Open Events">
    Navigate to **Events** from the left sidebar.
  </Step>

  <Step title="Create an event">
    Click **New event** and enter the date, title, category, source, and description.
  </Step>

  <Step title="Add context">
    Add labels or scope details that help people understand where the event applies, such as `environment = production`, a cloud provider, a team, or a service.
  </Step>

  <Step title="Save">
    Save the event so it appears on the Events page and can be added to Explorer charts.
  </Step>
</Steps>

## Set up event sources

To overlay events in Explorer, connect at least one event source:

<CardGroup>
  <Card title="GitHub" icon="github" href="/setup/events/github">
    Import deploys and PR merges.
  </Card>

  <Card title="CI/CD" icon="circle-nodes" href="/setup/events/ci-cd">
    Send pipeline and deployment events.
  </Card>

  <Card title="Custom API" icon="code" href="/setup/events/custom-api">
    Push business or technical events.
  </Card>
</CardGroup>

Cloud provider events, including Savings Plan purchases and CUD activations, are detected from billing data. No additional setup is required after billing data is connected.

<Tip>
  Pushing a custom event is a single `POST /v1/events` call with a JSON body. Add it to your CI/CD pipeline and see the [Custom API guide](/setup/events/custom-api) for the full spec.
</Tip>

## Frequently Asked Questions

<AccordionGroup>
  <Accordion title="Do events change billing data?">
    No. Events are metadata. They explain cost changes but do not modify billing rows, allocation rules, or cost metrics.
  </Accordion>

  <Accordion title="Can I backfill old events?">
    Yes. Create an event with a historical timestamp, or post one through the Events API. Costory places it on the correct date in Explorer.
  </Accordion>

  <Accordion title="Can saved events be used in reports?">
    Yes. When events are attached to a saved Explorer view or dashboard, the context can appear in scheduled reports that use that view.
  </Accordion>

  <Accordion title="Can I combine events with unit economics?">
    Yes. Add events to a chart that uses a [unit economics](/features/unit-economics) formula, such as cost per DAU or cost per transaction. This helps you see whether a deploy increased total spend while efficiency stayed on target.
  </Accordion>
</AccordionGroup>

## Related links

<CardGroup>
  <Card title="Events setup" icon="plug" href="/setup/events">
    Connect GitHub, CI/CD, provider, and API event sources.
  </Card>

  <Card title="Explorer" icon="magnifying-glass" href="/features/cost-explorer">
    Investigate cost changes with event context.
  </Card>

  <Card title="Unit Economics" icon="calculator" href="/features/unit-economics">
    Add formulas such as cost per user or cost per transaction.
  </Card>

  <Card title="Event Correlation use case" icon="timeline" href="/automate-reporting/event-correlation">
    Walk through cost change investigations with events.
  </Card>
</CardGroup>


# FinOps MCP: Cloud Cost Automation for AI Assistants
Source: https://docs.costory.io/features/mcp

Use the Costory FinOps MCP to query AWS, GCP, and Azure spend from Claude, Cursor, or VS Code. Investigate cost spikes, create alerts, and send Cost Reports via Model Context Protocol.

Connect the Costory FinOps MCP to Claude, Cursor, VS Code, or Dust and ask cost questions in chat instead of rebuilding queries in the billing console. Once your [billing data is connected](/get-started/welcome), the assistant calls structured MCP tools against normalized, allocated spend in your Costory workspace.

<iframe title="AI Assistant (MCP) walkthrough" />

## What is a FinOps MCP?

A **FinOps MCP** is a [Model Context Protocol](https://modelcontextprotocol.io) server that exposes cloud billing, allocation, and automation tools to AI assistants. Instead of pasting CUR exports into chat, the assistant calls tools like `query`, `create_alert`, and `create_report` against live data.

Costory FinOps MCP adds workspace context on top of raw provider billing: <Tooltip href="/docs/glossary#dimensions">Dimensions</Tooltip>, <Tooltip href="/docs/glossary#event-correlation">Event Correlation</Tooltip>, dashboards, alerts, and saved views.

|                      | Raw provider billing MCP           | Costory FinOps MCP                                       |
| -------------------- | ---------------------------------- | -------------------------------------------------------- |
| Data shape           | Provider-native line items         | Normalized, allocated spend across AWS, GCP, Azure, SaaS |
| Scope filters        | Account, service, tag (if tagged)  | Team, product, environment via dimensions                |
| Explain cost changes | Billing deltas only                | Cost diffs + deploys, metrics, and custom events         |
| Actions from chat    | Query only                         | Alerts, reports, dashboards, event annotations           |
| Setup                | IAM roles, local server, or Docker | One URL + OAuth                                          |

## Add Costory MCP to your Cursor / Claude / Dust

<Tabs>
  <Tab title="Claude Desktop">
    Claude Desktop supports MCP connectors natively. No local server or Node.js required.

    1. Open Claude Desktop settings
    2. Go to **Connectors**
    3. Click **Add custom connector**
    4. Enter **Costory** as the name and `https://app-api.costory.io/mcp` as the URL
    5. Click **Add**, then **Connect**
    6. A browser window will open. Log in with your Costory account
    7. Start asking about your costs

    <Frame>
      <img alt="Adding Costory as a custom connector in Claude Desktop" />
    </Frame>

    <Accordion title="Alternative: JSON config">
      You can also add the server via the developer config file (**Developer** > **Edit Config**). This method requires [Node.js](https://nodejs.org/):

      ```json theme={null}
      {
        "mcpServers": {
          "costory": {
            "command": "npx",
            "args": ["-y", "mcp-remote", "https://app-api.costory.io/mcp"]
          }
        }
      }
      ```
    </Accordion>
  </Tab>

  <Tab title="Claude Code">
    Claude Code connects natively over HTTP with OAuth. No `npx` or Node.js required.

    Run this in your terminal:

    ```bash theme={null}
    claude mcp add --transport http costory https://app-api.costory.io/mcp
    ```

    Then inside Claude Code, run `/mcp` and select **Authenticate**. A browser window will open for you to log in with your Costory account.

    For built-in FinOps skills and the Claude Code marketplace plugin, see the [costory-plugin repository](https://github.com/costory-io/costory-plugin).

    <Accordion title="Alternative: JSON config">
      You can also add the server directly to your project's `.mcp.json`:

      ```json theme={null}
      {
        "mcpServers": {
          "costory": {
            "type": "http",
            "url": "https://app-api.costory.io/mcp"
          }
        }
      }
      ```
    </Accordion>
  </Tab>

  <Tab title="VS Code (Copilot)">
    Add to your `.vscode/mcp.json`:

    ```json theme={null}
    {
      "servers": {
        "costory": {
          "type": "http",
          "url": "https://app-api.costory.io/mcp"
        }
      }
    }
    ```

    <Accordion title="Alternative: using mcp-remote">
      If the native HTTP connection doesn't work, you can use the `mcp-remote` bridge instead (requires [Node.js](https://nodejs.org/)):

      ```json theme={null}
      {
        "servers": {
          "costory": {
            "command": "npx",
            "args": ["-y", "mcp-remote", "https://app-api.costory.io/mcp"]
          }
        }
      }
      ```
    </Accordion>
  </Tab>

  <Tab title="Cursor">
    Add to your Cursor MCP settings:

    ```json theme={null}
    {
      "mcpServers": {
        "costory": {
          "type": "http",
          "url": "https://app-api.costory.io/mcp"
        }
      }
    }
    ```

    <Accordion title="Alternative: using mcp-remote">
      If the native HTTP connection doesn't work, you can use the `mcp-remote` bridge instead (requires [Node.js](https://nodejs.org/)):

      ```json theme={null}
      {
        "mcpServers": {
          "costory": {
            "command": "npx",
            "args": ["-y", "mcp-remote", "https://app-api.costory.io/mcp"]
          }
        }
      }
      ```
    </Accordion>
  </Tab>

  <Tab title="Dust">
    Dust supports remote MCP servers from the **Spaces** > **Tools** catalog.

    1. In Dust, open **Spaces** > **Tools**.
    2. Click **Add Tool**.
    3. Click **Add MCP Server**.
    4. Enter `https://app-api.costory.io/mcp` as the server URL.
    5. Select **Automatic** authentication.
    6. Complete the OAuth login flow with your Costory account.
    7. Add the synced Costory tool to the Space where your agent runs.
    8. Ask your cost questions in Dust.
  </Tab>
</Tabs>

<Note>
  On first connection, a browser window will open for you to log in with your Costory account. The `mcp-remote` fallback requires [Node.js](https://nodejs.org/) to be installed.
</Note>

## Example FinOps prompts

### Explore costs

Ask questions in natural language and the assistant will query your cost data:

* *"How much is the platform team spending on compute this month?"*
* *"Show me infrastructure costs for the recommendations API, broken down by service"*
* *"What's our total AI spend across Anthropic, OpenAI, and Bedrock?"*
* *"How much are we spending on storage?"*

### Compare periods

Understand how costs have changed over time:

* *"What's driving the cost increase on our data pipeline this week? Any related deploys or traffic changes?"*
* *"Did the March 15th release affect our search service costs?"*
* *"Compare this week's spend to last week for the data squad"*
* *"How have our compute costs changed compared to last month?"*

### Find information

Search across your entire Costory workspace:

* *"Find the saved view for the data team's Kubernetes costs"*
* *"What dashboards do we have for AI spend across providers?"*
* *"Show me alert history related to BigQuery pipelines"*

### Get recommendations

The assistant can suggest what to look at:

* *"What dimension should I group by to explain the billing-api cost spike?"*
* *"Based on deploy and metric history, what should I investigate next on the data pipeline increase?"*

### Take action

Go beyond analysis. Create views, alerts, events, and share reports:

* *"Save this query as a view called 'Recommendations API Infra Cost'"*
* *"Set up an alert if platform team compute costs go above \$10,000 this month"*
* *"Log an event: deployed billing-api v2 on March 15th"*
* *"Send this cross-provider AI cost report to the #finops Slack channel"*

## FinOps MCP workflows

Each workflow below shows a natural-language prompt, the MCP tools the assistant calls, and the JSON payload shape. These examples are specific to Costory workspace context. For plugin install and additional reference examples, see the [costory-plugin repository](https://github.com/costory-io/costory-plugin).

<AccordionGroup>
  <Accordion title="Correlate a deploy with a cost change">
    **Prompt:** *"Did the March 15 billing-api deploy affect our API service costs? Compare the week before and after."*

    **Tools:** `query` with period comparison, then `list_events` to pull deploy markers in the same window.

    **Result:** A side-by-side cost breakdown by service plus a timeline of deploys that overlapped the spike.

    <Accordion title="Underlying MCP calls (JSON)">
      **`query`**

      ```json theme={null}
      {
        "queries": [{
          "type": "cost",
          "name": "a",
          "metricId": "cost",
          "currency": "USD",
          "filterCel": "cos_service_name in [\"AmazonECS\", \"AmazonEKS\"] && cos_feature == \"billing-api\""
        }],
        "from": "2026-03-08",
        "to": "2026-03-21",
        "compare": { "from": "2026-03-01", "to": "2026-03-07" },
        "groupBy": "cos_service_name",
        "aggBy": "DAY"
      }
      ```

      **`list_events`**

      ```json theme={null}
      {
        "from": "2026-03-08",
        "to": "2026-03-21",
        "tags": ["billing-api"]
      }
      ```
    </Accordion>
  </Accordion>

  <Accordion title="Query allocated spend by team and environment">
    **Prompt:** *"How much is the platform team spending on compute in production this month?"*

    **Tools:** `query` with a `filterCel` scope built from your [dimensions](/features/tagging/dimensions).

    **Result:** Monthly compute spend for the platform team in production, grouped by cloud service.

    <Accordion title="Underlying MCP calls (JSON)">
      **`query`**

      ```json theme={null}
      {
        "queries": [{ "type": "cost", "name": "a", "metricId": "cost", "currency": "USD" }],
        "from": "2026-03-01",
        "to": "2026-03-31",
        "filterCel": "cos_team == \"platform\" && cos_environment == \"production\" && cos_category == \"compute\"",
        "groupBy": "cos_service_name"
      }
      ```
    </Accordion>
  </Accordion>

  <Accordion title="Track cost per business metric">
    **Prompt:** *"What is our cloud cost per DAU this month vs last month?"*

    **Tools:** `list_metrics` to resolve the metric ID, then `query` with a `formula`.

    **Result:** Unit cost trend with period-over-period comparison. See [Unit Economics](/features/unit-economics) for the same analysis in Explorer.

    <Accordion title="Underlying MCP calls (JSON)">
      **`query`**

      ```json theme={null}
      {
        "queries": [
          { "type": "cost", "name": "cost", "metricId": "cost", "currency": "USD" },
          { "type": "metric", "name": "dau", "metricId": "your-metric-id" }
        ],
        "formula": "cost / dau",
        "from": "2026-03-01",
        "to": "2026-03-31",
        "compare": { "from": "2026-02-01", "to": "2026-02-28" }
      }
      ```
    </Accordion>
  </Accordion>

  <Accordion title="Find the right dimension for a spike">
    **Prompt:** *"Something spiked on our data pipeline this week. What dimension should I split by?"*

    **Tools:** `suggest_groupby`, then `query` using the recommended dimension.

    **Result:** The assistant picks the most explanatory split (for example `cos_k8s_namespace` or `cos_service_name`) and drills down automatically.

    <Accordion title="Underlying MCP calls (JSON)">
      **Step 1: `suggest_groupby`**

      ```json theme={null}
      {
        "from": "2026-03-17",
        "to": "2026-03-24",
        "filterCel": "cos_feature == \"etl-jobs\""
      }
      ```

      **Step 2: `query` (using the suggested dimension)**

      ```json theme={null}
      {
        "queries": [{ "type": "cost", "name": "a", "metricId": "cost", "currency": "USD" }],
        "from": "2026-03-17",
        "to": "2026-03-24",
        "filterCel": "cos_feature == \"etl-jobs\"",
        "groupBy": "cos_k8s_namespace",
        "compare": { "from": "2026-03-10", "to": "2026-03-16" }
      }
      ```
    </Accordion>
  </Accordion>

  <Accordion title="Backtest an alert before creating it">
    **Prompt:** *"Alert me if daily BigQuery costs exceed \$2,000, but only if it would have fired at least once in the last 45 days."*

    **Tools:** `preview_alert` to backtest, then `create_alert` with the same condition. Resolve the Slack channel via `list_available_destinations`.

    **Result:** A validated alert with historical firing days and a link to edit it in Costory. Requires [Slack integration](/setup/collaboration/slack).

    <Accordion title="Underlying MCP calls (JSON)">
      **`preview_alert`**

      ```json theme={null}
      {
        "queries": [{
          "type": "cost",
          "name": "a",
          "metricId": "cost",
          "currency": "USD",
          "filterCel": "cos_service_name in [\"BigQuery\"]"
        }],
        "condition": "a > 2000",
        "dedup": { "kind": "CALENDAR", "calendarUnit": "DAY" },
        "lookbackDays": 45
      }
      ```

      **`create_alert` (after preview passes)**

      ```json theme={null}
      {
        "name": "Daily BigQuery threshold",
        "queries": [{
          "type": "cost",
          "name": "a",
          "metricId": "cost",
          "currency": "USD",
          "filterCel": "cos_service_name in [\"BigQuery\"]"
        }],
        "from": "2026-03-01",
        "to": "2026-03-31",
        "condition": "a > 2000",
        "dedup": { "kind": "CALENDAR", "calendarUnit": "DAY" },
        "notificationChannel": "SLACK",
        "slackChannelId": "YOUR_SLACK_CHANNEL_ID"
      }
      ```
    </Accordion>
  </Accordion>

  <Accordion title="Build a post-incident cost dashboard">
    **Prompt:** *"Build a dashboard for the billing-api outage: daily cost by service, filtered to billing-api, last 30 days."*

    **Tools:** `create_dashboard` with a scoped context and one or more widgets.

    **Result:** A shareable dashboard URL your team can reuse after incidents or cost reviews.

    <Accordion title="Underlying MCP calls (JSON)">
      **`create_dashboard`**

      ```json theme={null}
      {
        "name": "Billing API outage - March 2026",
        "context": {
          "metricId": "cost",
          "currency": "USD",
          "conditionsCel": "cos_feature == \"billing-api\"",
          "from": "2026-02-24",
          "to": "2026-03-25"
        },
        "widgets": [{
          "type": "LINE",
          "queries": [{ "type": "cost", "name": "a", "metricId": "cost", "currency": "USD" }],
          "groupBy": "cos_service_name",
          "extendDashboardConditions": true,
          "aggBy": "DAY"
        }]
      }
      ```
    </Accordion>
  </Accordion>

  <Accordion title="Explore how to split costs, then publish a virtual dimension">
    **Prompt:** *"How should we split our spend by team? Once we've found a clean split, publish it as a Team dimension."*

    **Tools:** Explore first with `suggest_groupby` and `query` (which field best separates the cost) and `search` type `dimensions` (the real values behind each concept). Then commit: `create_virtual_dimension_draft`, `preview_virtual_dimension_draft` to check per-rule costs and leftover %, `virtual_dimension_overlap_matrix` to catch shadowing, and `publish_virtual_dimension`.

    **Result:** A published Team dimension across Explorer, dashboards, alerts, and reports after the refresh. The exploration loop is the point; drafting and publishing are the easy last steps. See [Dimensions](/features/tagging/dimensions#explore-and-build-allocation-with-your-ai-assistant).

    <Accordion title="Underlying MCP calls (JSON)">
      **`suggest_groupby` (which field best explains the spend?)**

      ```json theme={null}
      {
        "from": "2026-03-01",
        "to": "2026-03-31",
        "filterCel": "cos_category == \"compute\""
      }
      ```

      **`create_virtual_dimension_draft` (after the split is validated)**

      ```json theme={null}
      {
        "name": "Team",
        "rules": [
          { "conditionCel": "cos_gcp_project_id.startsWith(\"eng-\")", "allocation": { "type": "value", "value": "Engineering" } },
          { "conditionCel": "cos_gcp_project_id.startsWith(\"data-\")", "allocation": { "type": "value", "value": "Data" } }
        ]
      }
      ```

      **`preview_virtual_dimension_draft`**

      ```json theme={null}
      {
        "virtualDimensionId": "VDIM_ID",
        "mode": "costs"
      }
      ```

      **`publish_virtual_dimension` (after preview and overlap check pass)**

      ```json theme={null}
      {
        "virtualDimensionId": "VDIM_ID"
      }
      ```
    </Accordion>
  </Accordion>

  <Accordion title="Reallocate shared cost by a usage metric">
    **Prompt:** *"Split our shared Cloud SQL bill across teams based on schema size from our usage metric."*

    **Tools:** `list_metrics` (no args) to pick the usage-metric datasource, `list_metrics` with `datasourceId` to learn its group-by dimensions, `query` (type `metric`) to inspect values, then `create_virtual_dimension_draft` / `update_virtual_dimension_draft` with a telemetry allocation, `preview_virtual_dimension_draft`, and `publish_virtual_dimension`.

    **Result:** A shared cost split proportionally by actual usage. See [Shared Cost Allocation](/features/tagging/shared-cost-allocation).

    <Accordion title="Underlying MCP calls (JSON)">
      **`list_metrics` (resolve the datasource's group-by dimensions)**

      ```json theme={null}
      {
        "datasourceId": "USAGE_METRIC_DATASOURCE_ID"
      }
      ```

      **`update_virtual_dimension_draft` (telemetry allocation)**

      ```json theme={null}
      {
        "virtualDimensionId": "VDIM_ID",
        "rules": [{
          "conditionCel": "cos_service_name in [\"CloudSQL\"]",
          "allocation": {
            "type": "telemetry",
            "datasourceId": "USAGE_METRIC_DATASOURCE_ID",
            "groupBy": "schema"
          }
        }]
      }
      ```
    </Accordion>
  </Accordion>
</AccordionGroup>

## Example conversations

<AccordionGroup>
  <Accordion title="Investigating a cost spike">
    **You:** *"Why did our costs go up last week?"*

    The assistant will:

    1. Call `get_context` to load dimensions and recent dashboards
    2. Run `query` with a week-over-week comparison
    3. Call `list_events` for deploys and provider events in the same period
    4. Highlight likely causes with a timeline of what changed first
    5. Call `suggest_actions` for follow-ups (drill deeper, set up an alert, share to Slack)

    <Accordion title="Underlying MCP calls (JSON)">
      **`query`**

      ```json theme={null}
      {
        "queries": [{ "type": "cost", "name": "a", "metricId": "cost", "currency": "USD" }],
        "from": "2026-03-17",
        "to": "2026-03-24",
        "compare": { "from": "2026-03-10", "to": "2026-03-16" },
        "groupBy": "cos_service_name",
        "aggBy": "DAY"
      }
      ```

      **`list_events`**

      ```json theme={null}
      {
        "from": "2026-03-17",
        "to": "2026-03-24"
      }
      ```
    </Accordion>
  </Accordion>

  <Accordion title="Cross-provider AI cost review">
    **You:** *"What's our total AI spend across Anthropic, OpenAI, and Bedrock this month? Break it down by team and model."*

    The assistant will:

    1. Query AI-related spend across Anthropic, OpenAI, and AWS Bedrock
    2. Combine results into one total with a provider-level breakdown
    3. Break down the same spend by team and model
    4. Offer to save the view or send the report to Slack

    <Accordion title="Underlying MCP calls (JSON)">
      **`query`**

      ```json theme={null}
      {
        "queries": [{
          "type": "cost",
          "name": "a",
          "metricId": "cost",
          "currency": "USD",
          "filterCel": "cos_provider in [\"Anthropic\", \"OpenAI\", \"AWS\"] && cos_category == \"ai\""
        }],
        "from": "2026-03-01",
        "to": "2026-03-31",
        "groupBy": "cos_team"
      }
      ```
    </Accordion>
  </Accordion>

  <Accordion title="Building a cost report">
    **You:** *"Show me our top 5 services by cost this month, then send it to #cloud-costs on Slack"*

    The assistant will:

    1. Query costs grouped by service for the current month
    2. Schedule a report via `create_report`
    3. Deliver a formatted chart to the Slack channel

    <Accordion title="Underlying MCP calls (JSON)">
      **`create_report`**

      ```json theme={null}
      {
        "scheduledPeriod": "WEEKLY",
        "widget": {
          "type": "TOP_FLOP",
          "queries": [{
            "type": "cost",
            "name": "a",
            "metricId": "cost",
            "currency": "USD",
            "groupBy": "cos_service_name"
          }],
          "topN": 5,
          "flopN": 0
        },
        "destinations": [{ "destinationType": "SLACK", "channelId": "YOUR_SLACK_CHANNEL_ID" }]
      }
      ```
    </Accordion>
  </Accordion>

  <Accordion title="Setting up monitoring">
    **You:** *"Create an alert if our daily compute costs go above \$5,000"*

    The assistant will:

    1. Run `preview_alert` to confirm the threshold would have fired recently
    2. Create a cost alert with `create_alert`
    3. Return a link to review and edit the alert in Costory

    <Accordion title="Underlying MCP calls (JSON)">
      **`create_alert`**

      ```json theme={null}
      {
        "name": "Daily compute threshold",
        "queries": [{
          "type": "cost",
          "name": "a",
          "metricId": "cost",
          "currency": "USD",
          "filterCel": "cos_category == \"compute\""
        }],
        "from": "2026-03-01",
        "to": "2026-03-31",
        "condition": "a > 5000",
        "dedup": { "kind": "CALENDAR", "calendarUnit": "DAY" },
        "notificationChannel": "SLACK",
        "slackChannelId": "YOUR_SLACK_CHANNEL_ID"
      }
      ```
    </Accordion>
  </Accordion>
</AccordionGroup>

## Why Costory MCP?

Direct access to AWS CUR or a GCP MCP server gives you provider-native line items and dimensions. Costory MCP adds your Costory workspace context so you can ask higher-level cost questions and take action in the same flow.

* Query spend by team, product, or feature because <Tooltip href="/docs/glossary#dimensions">dimensions</Tooltip> and <Tooltip href="/docs/glossary#cost-allocation">cost allocation</Tooltip> are already modeled.
* Ask one question across AWS, GCP, Azure, Datadog, Anthropic, OpenAI, and Cursor instead of wiring and maintaining separate MCP servers per provider.
* Explain **why** costs moved by using <Tooltip href="/docs/glossary#event-correlation">Event Correlation</Tooltip> with deploys, Datadog metrics, and provider events in the same investigation.
* Continue from saved views, dashboards, team structures, alert history, and prior investigations so your assistant has persistent workspace context.
* Connect with one URL and OAuth (no IAM credentials, Docker, or local server setup), and use it in Claude, Cursor, VS Code, or Claude Code.
* Take action directly from chat by creating alerts, saving views, logging events, and sending Cost Reports.
* Use pre-computed allocation rules and shared costs so each query starts from resolved context instead of rebuilding logic from raw CUR data.

## MCP tools reference

<Note>
  For plugin install, FinOps skills, and the full tool catalog grouped by workflow, see the [costory-plugin repository](https://github.com/costory-io/costory-plugin).
</Note>

### Discovery and context

| Tool                    | Description                                                                                                                                                                                                                                                                                               | Key parameters                       |                                                                                                                                     |
| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------- |
| `get_context`           | Returns a workspace overview: all available dimensions (with top values), popular group-by dimensions, and recently updated dashboards. Call this first in every conversation.                                                                                                                            | None                                 |                                                                                                                                     |
| `list_organizations`    | Lists all organizations the authenticated user has access to. Use when you belong to multiple organizations.                                                                                                                                                                                              | None                                 |                                                                                                                                     |
| `search`                | Unified full-text search across dimension values, events, alerts, dashboards (with `conditionsCel`), templates, reports, virtual dimensions, budgets, and metrics. Pass a `type` filter (e.g. `dimensions`, `virtual_dimensions`) to narrow to exact CEL field names and values.                          | `query`, `type` (optional)           |                                                                                                                                     |
| `suggest_groupby`       | Recommends the best dimension to group costs by, given an optional scope filter and date range.                                                                                                                                                                                                           | `from`, `to`, `filterCel` (optional) |                                                                                                                                     |
| `list_metrics`          | Lists all existsing business metrics for the organization. Returns IDs usable in `query` as `{ type: "metric", metricId: "..." }`. Pass a `datasourceId` to return that usage-metric datasource's available group-by dimensions instead, needed to author a telemetry (split-by-usage-metric) allocation. | `datasourceId` (optional)            | Also returns external metrics that can be used in `query` as `{ type: "externalMetric", integrationId: "...", metricName: "..." }`. |
| `suggest_usage_metrics` | Suggests infrastructure usage metric units (e.g. `k8s_cpu_hours`, `network_bytes_out`) relevant to a billing scope. Call before combining cost with usage in `query`.                                                                                                                                     | `filterCel` (optional)               |                                                                                                                                     |
| `get_skill`             | Loads a guided workflow for a complex task before you start it. Only `virtual_dimensions` is available today. Call it before building or iterating on a virtual dimension.                                                                                                                                | `skillId`                            |                                                                                                                                     |

### Query and data

| Tool                         | Description                                                                                                                                                                                                                                                                                | Key parameters                                                                                       |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------- |
| `query`                      | Core data tool. Runs unified queries for cloud costs, custom business metrics, usage metrics, budgets, period comparisons, and formulas. Supports query types: `cost`, `metric`, `usage`, `externalMetric`, `budget`, `formula`. Chart types: `BAR`, `LINE`, `AREA`, `WATERFALL`, `TABLE`. | `queries[]`, `from`, `to`, `aggBy`, `compare` (optional), `filterCel`, `groupBy`, `limit` (optional) |
| `get`                        | Fetches a full resource by ID: dashboard, budget, or cost alert. Budget responses include `budgetVersionId` and alignment filters. Dashboard responses include widget grid positions and query configs. Alert responses include `firingHistory`.                                           | `id`                                                                                                 |
| `get_dashboard_widget_data`  | Runs a saved dashboard widget and returns its data without re-specifying the query config. Applies dashboard `conditionsCel` when the widget has `extendDashboardConditions: true`.                                                                                                        | `dashboardId`, `widgetId`                                                                            |
| `get_dashboard_widget_image` | Renders a saved widget as a PNG chart, uploads to GCS, and returns the image URL (and optionally inline base64). Does not work for text/table-only widgets.                                                                                                                                | `dashboardId`, `widgetId`, `includeBinaryImage` (optional)                                           |

#### `query` query types

| Type             | Purpose                                                                                                               | ID source                                                               |
| ---------------- | --------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
| `cost`           | Cloud spend                                                                                                           | `metricId` (default `"cost"`), `currency` (default `"USD"`)             |
| `metric`         | Custom business metric                                                                                                | `list_metrics`                                                          |
| `usage`          | Infra usage metric (CPU hours, network bytes)                                                                         | `suggest_usage_metrics`                                                 |
| `externalMetric` | External-metric integration (Tsuga, BigQuery, [Custom metrics](/setup/usage-metrics/custom-metrics-push), and others) | `integrationId` and `metricName` from `list_metrics` (external metrics) |
| `budget`         | Budget line                                                                                                           | `get`, then `budgetVersionId` (not the parent budget ID from `search`)  |
| `formula`        | Math over named queries                                                                                               | e.g. `"a / b"`                                                          |

### Dashboards

| Tool               | Description                                                                                                                                                                                                                                                                          | Key parameters                 |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------ |
| `create_dashboard` | Creates a new dashboard with one or more widgets. Dashboard-level `context` (metricId, groupBy, currency, `conditionsCel`, date preset) is inherited by widgets. Set `extendDashboardConditions: true` on widgets that should respect the dashboard filter. Returns a dashboard URL. | `name`, `context`, `widgets[]` |
| `update_dashboard` | Adds, replaces, or removes widgets on an existing dashboard. Operations are applied atomically. Returns a dashboard URL.                                                                                                                                                             | `dashboardId`, `operations[]`  |

#### `update_dashboard` operations

| Op        | Description                                                                           |
| --------- | ------------------------------------------------------------------------------------- |
| `add`     | Append a new widget. Optional `x`, `y`, `w`, `h` for grid placement (12-column grid). |
| `replace` | Overwrite an existing widget in place, keeping its grid position.                     |
| `remove`  | Delete a widget by ID.                                                                |

### Alerts

| Tool            | Description                                                                                                                                                                                                                               | Key parameters                                                                 |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| `list_alerts`   | Lists all cost alerts and budget alerts with their current status and configuration.                                                                                                                                                      | `type` (`cost` \| `budget` \| `all`)                                           |
| `preview_alert` | Backtests a cost-alert condition against historical data before creating it. Returns firing days, per-group fires, and notification count after dedup.                                                                                    | `queries[]`, `condition`, `dedup` (optional), `lookbackDays` (default 45)      |
| `create_alert`  | Creates a cost alert that monitors queries and notifies when a condition fires. Condition examples: `a > 1000`, `rollingSum(a, 7, DAY) > 50000`. Resolve Slack/Teams channel IDs via `list_available_destinations`. Returns an alert URL. | `name`, `queries[]`, `from`, `to`, `condition`, `dedup`, `notificationChannel` |

### Virtual dimensions

Manage [virtual dimensions](/features/tagging/dimensions#explore-and-build-allocation-with-your-ai-assistant) end-to-end. Edits happen on a draft; publishing is explicit and triggers a BigQuery refresh. Rules are always read and written as CEL (first match wins), with an automatic catch-all leftover bucket.

| Tool                               | Description                                                                                                                                                                                                       | Key parameters                                          |
| ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- |
| `list_virtual_dimensions`          | Finds a virtual dimension by name, tag, or status and resolves its stable `virtualDimensionId` and immutable `bqName`. Paginated (default 50, cap 100).                                                           | `query` (optional), `status` (optional)                 |
| `get_virtual_dimension`            | Returns the full state: published rules plus any pending draft (as CEL), the separate leftover rule, derived values, compute status, and dependencies (alerts, budgets, other dimensions).                        | `virtualDimensionId`                                    |
| `create_virtual_dimension_draft`   | Creates a brand-new virtual dimension as a draft. `tagNames` resolve to IDs server-side; a leftover bucket is added automatically. Rejects invalid payloads.                                                      | `name`, `rules[]`, `tagNames` (optional)                |
| `update_virtual_dimension_draft`   | Edits an existing dimension's draft. Declarative: send the full desired `rules` array (not diffs). Seeds a draft from published state if none exists. Omit `rules` to change metadata only.                       | `virtualDimensionId`, `rules[]` (optional)              |
| `preview_virtual_dimension_draft`  | Backtests the draft against BigQuery before publishing. `mode: "costs"` returns trailing-30-day per-rule costs and leftover share %; `mode: "breakdown"` drills into one rule's top values at a chosen `groupBy`. | `virtualDimensionId`, `mode`, `groupBy` (for breakdown) |
| `virtual_dimension_overlap_matrix` | Returns pairwise overlap for all named rules in one query to detect rule shadowing (a broad earlier rule swallowing spend a later rule should catch).                                                             | `virtualDimensionId`                                    |
| `publish_virtual_dimension`        | Validates the persisted draft, promotes it to production, and starts the BigQuery refresh. Returns the immutable `bqName` and `computeStatus: REFRESHING` (async).                                                | `virtualDimensionId`                                    |

<Note>
  Virtual dimension writes are authenticated as your user (excluded from the GCP service route). Renaming the leftover bucket and using live external-metric integrations as a reallocation source remain web-app-only.
</Note>

### Events

| Tool           | Description                                                                                                                                 | Key parameters                                                                       |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| `list_events`  | Lists events (deployments, business changes, provider updates) within a date range. Use to correlate cost changes with real-world events.   | `from`, `to`, `category` (optional), `tags` (optional)                               |
| `create_event` | Creates an event annotation on the cost timeline. Strongly recommended: attach a `widget` definition tying the event to the relevant chart. | `name`, `date`, `description`, `category`, `tags` (optional), `widget` (recommended) |

### Reports and notifications

| Tool                          | Description                                                                                                                                             | Key parameters                                |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------- |
| `list_available_destinations` | Lists every destination the org can deliver reports or alerts to: Slack channels, Teams channels, and email. Each provider includes a `connected` flag. | None                                          |
| `create_report`               | Schedules a recurring report digest via Slack, Teams, or email. Cadence: `DAILY`, `WEEKDAYS`, `WEEKLY`, `MONTHLY`. Returns a report URL.                | `scheduledPeriod`, `widget`, `destinations[]` |

#### `create_report` widget types

| Type             | Description                                             |
| ---------------- | ------------------------------------------------------- |
| `DASHBOARD_PDF`  | Snapshot of an existing dashboard (ID from `search`).   |
| `GRAPH_SNAPSHOT` | Ad-hoc query snapshot (same config shape as `query`).   |
| `TOP_FLOP`       | Top N gainers + bottom N losers vs the previous period. |

### Organization metadata

| Tool                 | Description                                                                                                    | Key parameters          |
| -------------------- | -------------------------------------------------------------------------------------------------------------- | ----------------------- |
| `list_teams`         | Lists teams the current user belongs to, including each team's scopes (pre-defined `filterCel` strings).       | None                    |
| `list_tags`          | Lists all tags in the organization with usage counts across dashboards, views, explorers, and alerts.          | None                    |
| `set_dashboard_tags` | Sets (replaces) the full tag list on a dashboard. Pass existing tag IDs or new tag objects `{ name, color? }`. | `dashboardId`, `tags[]` |
| `set_dashboard_team` | Assigns a dashboard to a team, or removes it (`teamId: null`).                                                 | `dashboardId`, `teamId` |
| `delete_tag`         | Deletes an unused tag. Only tags with zero tagged resources can be deleted.                                    | `tagId`                 |

### Documentation

| Tool                     | Description                                                                                       | Key parameters                            |
| ------------------------ | ------------------------------------------------------------------------------------------------- | ----------------------------------------- |
| `search_documentation`   | Searches the public Costory product documentation (guides, API references, feature explanations). | `query`                                   |
| `get_documentation_page` | Retrieves the full content of a documentation page by path. Use after `search_documentation`.     | `page` (e.g. `"use-cases/cost-explorer"`) |

### Agent helpers

| Tool              | Description                                                                                                                                                         | Key parameters         |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- |
| `suggest_actions` | Suggests follow-up actions based on investigation context (save a view, set up an alert, share to Slack, drill down, compare periods). Call after `query` or `get`. | `hasEvents`, `hasDiff` |

## Tips

<CardGroup>
  <Card title="Be specific about time" icon="calendar">
    *"last 30 days"*, *"this quarter"*, *"March 2026"*. The assistant understands natural date ranges.
  </Card>

  <Card title="Use your own names" icon="magnifying-glass">
    Mention service names, team names, or project names. The assistant searches your workspace to find the right dimensions.
  </Card>

  <Card title="Ask follow-ups" icon="arrows-split-up-and-left">
    After a query, drill deeper: *"now filter that to just eu-west-1"* or *"break that down by SKU"*.
  </Card>

  <Card title="Multi-org support" icon="building">
    If you belong to multiple organizations, just mention which one: *"show costs for acme-prod"*.
  </Card>
</CardGroup>

## FAQ

<AccordionGroup>
  <Accordion title="What is a FinOps MCP?">
    A FinOps MCP is a Model Context Protocol server that lets AI assistants query cloud billing data and run FinOps actions (alerts, reports, dashboards) through structured tool calls instead of raw CSV exports.
  </Accordion>

  <Accordion title="How is Costory FinOps MCP different from an AWS billing MCP?">
    Provider billing MCPs return native line items for one cloud. Costory FinOps MCP returns normalized, allocated spend across AWS, GCP, Azure, and SaaS providers, with dimensions, event correlation, and automation tools in the same connection.
  </Accordion>

  <Accordion title="Which AI clients support FinOps MCP?">
    Costory FinOps MCP works with Claude Desktop, Claude Code, Cursor, VS Code (Copilot), and Dust. Connect with `https://app-api.costory.io/mcp` and authenticate via OAuth.
  </Accordion>

  <Accordion title="Do I need to run a local MCP server?">
    No. Costory FinOps MCP is a hosted remote server. Claude Desktop, Claude Code, Cursor, and VS Code connect over HTTP. A local `mcp-remote` bridge is available as a fallback if your client does not support HTTP transport natively.
  </Accordion>

  <Accordion title="Can FinOps MCP create alerts and Cost Reports?">
    Yes. The assistant can call `create_alert`, `create_report`, and `list_available_destinations` to set up [cloud cost alerts](/features/alerts) and [Cost Reports](/features/slack-reports) directly from chat.
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Browser doesn't open for login">
    If using Claude Desktop's native connector, try disconnecting and reconnecting in **Settings** > **Connectors**. If using the `mcp-remote` fallback, make sure `npx` is available in your PATH.
  </Accordion>

  <Accordion title="Claude Code: 'does not support dynamic client registration'">
    Make sure you're using the native HTTP transport (`type: "http"`) rather than `mcp-remote`. Run `/mcp` in Claude Code, then select **Authenticate** to trigger the OAuth flow.
  </Accordion>

  <Accordion title="'Not authenticated' errors">
    Your session may have expired. Restart the MCP server in your AI client to re-authenticate. In Claude Code, run `/mcp` and select **Authenticate**.
  </Accordion>

  <Accordion title="'Multiple organizations' error">
    Specify which org you want in your message: *"show costs for \[your-org-slug]"*.
  </Accordion>

  <Accordion title="No results from search">
    Try shorter, simpler search terms, e.g. *"kubernetes"* instead of *"kubernetes production dashboard"*.
  </Accordion>
</AccordionGroup>

## Related links

<CardGroup>
  <Card title="Get started" icon="rocket" href="/get-started/welcome">
    Connect billing data before using FinOps MCP
  </Card>

  <Card title="Explorer" icon="magnifying-glass" href="/features/cost-explorer">
    Build the queries your assistant reuses in chat
  </Card>

  <Card title="Dimensions" icon="layer-group" href="/features/tagging/dimensions">
    Allocate spend by team, product, or environment
  </Card>

  <Card title="Events" icon="timeline" href="/features/events">
    Correlate deploys with cost charts
  </Card>

  <Card title="Unit Economics" icon="calculator" href="/features/unit-economics">
    Build cost per user, request, or transaction
  </Card>

  <Card title="Cost Reports" icon="paper-plane" href="/features/slack-reports">
    Schedule recurring cost snapshots to Slack, Teams, or email
  </Card>

  <Card title="Cloud cost alerts" icon="triangle-exclamation" href="/features/alerts">
    Threshold and anomaly alerts with Slack notifications
  </Card>

  <Card title="Slack setup" icon="plug" href="/setup/collaboration/slack">
    Connect Slack so MCP can deliver reports and alerts
  </Card>

  <Card title="Plugin repository" icon="github" href="https://github.com/costory-io/costory-plugin">
    Claude Code marketplace install and FinOps skills
  </Card>

  <Card title="Query Costs API" icon="code" href="/api-reference/queries/overview">
    Call the same query endpoint over HTTP without an MCP client
  </Card>
</CardGroup>


# Tag & Allocate Cloud Costs
Source: https://docs.costory.io/features/tagging

FinOps cost allocation made simple. Create dimensions, allocate untagged resources, and split shared costs across AWS, GCP, and Azure without touching your cloud console.

Costory maps inconsistent cloud billing data to clean, team-level cost breakdowns. Use dimensions to unify tags, allocate untagged resources, and split shared infrastructure costs, all from one place and applied retroactively to your historical data.

### See it in action

<CardGroup>
  <Card title="Automated Environment Visibility" icon="eye" href="/use-cases/automated_env_allocation/visibility">
    Unify inconsistent environment tags across providers and get a clean cost-per-environment breakdown in minutes.
  </Card>

  <Card title="Allocate a Shared Cloud SQL Database" icon="database" href="/use-cases/allocate_shared_cloud_sql_database/allocate">
    Split the cost of a shared database across the teams that use it, based on actual usage metrics.
  </Card>

  <Card title="Reallocate API Costs" icon="arrow-right-arrow-left" href="/use-cases/reallocate_api_costs">
    Reallocate untagged API costs to teams using an external usage metric like API call counts.
  </Card>
</CardGroup>

***

## How it works

```mermaid theme={null}
%%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#EEF2FF', 'primaryTextColor': '#1D3C93', 'primaryBorderColor': '#C7D2FE', 'lineColor': '#6366F1', 'secondaryColor': '#F0FDF4', 'tertiaryColor': '#FFF7ED'}}}%%
graph LR
    subgraph messy ["🏷️ Messy Tags"]
        R1["Env = prod"]
        R2["environment = production"]
        R3["k8s_label_env = prd"]
    end

    subgraph meta ["📦 Billing Metadata"]
        R4["namespace: payments"]
        R5["resource: api-gateway-eu"]
        R6["account: 1234-prod"]
    end

    DIM["⚙️ <b>Dimensions</b><br/>Merge tag keys · Normalize values · Apply rules"]

    CLEAN["✅ environment = production"]

    subgraph output ["🎯 Business Concepts"]
        T["Team: Payments"]
        BU["Business Unit: Commerce"]
        PL["P&L Line: Revenue"]
    end

    R1 --> DIM
    R2 --> DIM
    R3 --> DIM
    DIM --> CLEAN
    CLEAN --> T
    R4 --> DIM
    R5 --> DIM
    R6 --> DIM
    DIM --> BU
    DIM --> PL

    style DIM fill:#DBEAFE,stroke:#3B82F6,stroke-width:2px,color:#1E3A8A
    style CLEAN fill:#D1FAE5,stroke:#10B981,stroke-width:2px,color:#065F46
    style T fill:#FEF3C7,stroke:#F59E0B,stroke-width:2px,color:#92400E
    style BU fill:#FEF3C7,stroke:#F59E0B,stroke-width:2px,color:#92400E
    style PL fill:#FEF3C7,stroke:#F59E0B,stroke-width:2px,color:#92400E
    style R1 fill:#FEE2E2,stroke:#EF4444,stroke-width:1px,color:#991B1B
    style R2 fill:#FEE2E2,stroke:#EF4444,stroke-width:1px,color:#991B1B
    style R3 fill:#FEE2E2,stroke:#EF4444,stroke-width:1px,color:#991B1B
    style R4 fill:#F3F4F6,stroke:#9CA3AF,stroke-width:1px,color:#374151
    style R5 fill:#F3F4F6,stroke:#9CA3AF,stroke-width:1px,color:#374151
    style R6 fill:#F3F4F6,stroke:#9CA3AF,stroke-width:1px,color:#374151
```

Costory's allocation workflow has two core parts: dimensions for consistent reporting fields, and shared cost allocation for costs that need proportional splits.

<CardGroup>
  <Card title="Dimensions" icon="layer-group" href="/features/tagging/dimensions">
    Merge native tags and labels, normalize values, and define virtual dimensions from rules.
  </Card>

  <Card title="Shared Cost Allocation" icon="chart-pie" href="/features/tagging/shared-cost-allocation">
    Split shared infrastructure costs across teams based on actual usage metrics from any External metric source.
  </Card>
</CardGroup>

***

<Card title="Get started in 30 minutes" icon="play" href="/get-started/quickstart">
  Sign up for free, connect your cloud provider, and see your costs allocated. No engineering tickets required.
</Card>

## Frequently Asked Questions

<AccordionGroup>
  <Accordion title="What is virtual tagging?">
    Virtual tagging lets you assign cost allocation values to cloud resources without modifying the resources themselves. In Costory, this is done with [dimensions](/features/tagging/dimensions), which support imported tags, rule-based virtual dimensions, usage-based shared cost splitting, and retroactive application to historical data.
  </Accordion>

  <Accordion title="What is the difference between an imported dimension and a virtual dimension?">
    An imported dimension points several native tags or labels at one reporting field. For example, `aws:Environment`, `env`, and `environment` can become one `Environment` dimension.

    A virtual dimension defines values from rules. For example, a `Team` virtual dimension can map resources to teams using project IDs, namespaces, account names, or other billing metadata.
  </Accordion>

  <Accordion title="Can I use Costory for chargeback and showback?">
    Yes. Dimensions let you allocate 100% of your cloud bill to teams, products, or cost centers, which is the foundation of any chargeback or showback model. Combined with [Cost Reports](/features/slack-reports) and [Explorer](/features/cost-explorer), you can automate the reporting side too.
  </Accordion>

  <Accordion title="How do I handle untagged resources?">
    Virtual dimensions can allocate untagged resources using any available billing metadata: account ID, service name, resource name, Kubernetes namespace, region, and more. You don't need to go back and tag resources in your cloud console.
    For network costs, you can rely on [shared cost allocation](/features/tagging/shared-cost-allocation) based on usage metrics.
  </Accordion>

  <Accordion title="Does this work retroactively on historical data?">
    Yes. When you create or update a dimension, Costory reprocesses your billing history so the new allocation applies to past months as well.
  </Accordion>

  <Accordion title="Can I manage dimensions via GitHub?">
    Yes. Virtual dimensions can be created and updated using a JSON Schema, so you can version-control allocation logic from the UI.
  </Accordion>

  <Accordion title="How often are allocations recomputed?">
    Allocations are recomputed every time Costory ingests new billing data from your providers, typically daily. If you update a rule or a usage metric, historical data is also reprocessed automatically.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup>
  <Card title="Explore Your Costs" icon="chart-bar" href="/features/cost-explorer">
    Use your new allocations in Explorer
  </Card>

  <Card title="Automate FinOps Reports" icon="slack" href="/features/slack-reports">
    Send cost-per-team reports to Slack automatically
  </Card>

  <Card title="Allocate a Shared Database" icon="database" href="/use-cases/allocate_shared_cloud_sql_database/allocate">
    Step-by-step: split a Cloud SQL bill across teams
  </Card>

  <Card title="Environment Cost Visibility" icon="eye" href="/use-cases/automated_env_allocation/visibility">
    Unify environment tags and see cost per env in minutes
  </Card>
</CardGroup>


# Dimensions
Source: https://docs.costory.io/features/tagging/dimensions

Create cloud cost allocation dimensions that merge native AWS, GCP, and Azure tags, normalize values, and define rule-based virtual dimensions for team, product, or environment reporting.

**Dimensions** are Costory reporting fields. They map provider-specific tags, labels, and billing metadata to consistent values you can group, filter, allocate, alert, and report on across AWS, GCP, and Azure.

Costory resolves dimensions on top of your billing export and recomputes history on every change, so a dimension reads the same in [Explorer](/features/cost-explorer), dashboards, alerts, and reports. The UI and the [Costory MCP](/features/mcp) write the same definitions: rules you build in the app are the same CEL conditions an agent drafts and publishes through the virtual dimension tools.

<Frame>
  <img alt="Costory Dimensions page listing imported labels and virtual dimensions" />
</Frame>

## Overview

There are two kinds of dimension.

An **imported dimension** points several native tags or labels at the same concept. Map `aws:Environment`, `env`, and `environment` into one `Environment` dimension so filters and splits stay consistent across providers.

A **virtual dimension** derives its values from rules instead of an existing tag. Each rule is a CEL condition evaluated top to bottom, first match wins. A `Team` virtual dimension can route rows where `cos_gcp_project_id.startsWith("eng-")` to `Engineering` and send everything else to a leftover bucket.

Common uses:

* Collapse duplicate tag keys across AWS, GCP, and Azure into one field
* Normalize values such as `prod`, `prd`, and `production`
* Allocate untagged resources to teams, products, or cost centers
* Build shared dashboards, alerts, and reports on stable business fields

## Key terms used in this article

* **Dimension**: A Costory reporting field used to filter, group, allocate, or scope costs.
* **Imported dimension**: A dimension built from native provider tags, labels, or billing metadata.
* **<Tooltip href="/docs/glossary#virtual-dimensions">Virtual dimension</Tooltip>**: A dimension whose values come from CEL rules you define in Costory.
* **Leftover bucket**: The automatic catch-all value for any row that matches no rule. A large leftover share signals a missing or too-narrow rule.

See the [Glossary](/docs/glossary) for a full list of terms.

## Create a dimension from native tags and labels

Use imported dimensions when the data already exists in your cloud billing export, but the names or values are inconsistent.

<Steps>
  <Step title="Open Dimensions">
    Navigate to **Dimensions** from the left sidebar.
  </Step>

  <Step title="Add a dimension">
    Click **+ Add new dimension**, then select the native tags or labels you want to merge.

    <Frame>
      <img alt="Selecting native tag and label sources to create a Costory dimension" />
    </Frame>
  </Step>

  <Step title="Choose the reporting name">
    Pick the name you want Costory users to see, such as `environment`, `team`, or `cost_center`.
  </Step>

  <Step title="Normalize values">
    Review suggested value mappings and adjust them. For example, map `prod`, `prd`, and `production` to `production`.

    <Frame>
      <img alt="Environment dimension editor remapping values to canonical names" />
    </Frame>
  </Step>

  <Step title="Publish">
    Click **Publish all changes**. Costory reprocesses historical data so the dimension is available in [Explorer](/features/cost-explorer), [Dashboards](/features/dashboards), [Alerts](/features/alerts), and [Reports](/features/slack-reports).
  </Step>
</Steps>

## Create a virtual dimension from rules

Use virtual dimensions when the right grouping does not exist as a clean tag. Rules can use billing metadata, imported dimensions, or other virtual dimensions.

<Steps>
  <Step title="Create the virtual dimension">
    Open **Dimensions**, click **+ Add new dimension** > **Virtual dimension**, and enter a name such as `team`, `business_unit`, or `product`.

    <Frame>
      <img alt="Dimensions page with Add new dimension menu showing Dimension and Virtual dimension options" />
    </Frame>
  </Step>

  <Step title="Define rules">
    Add conditions that map cost rows to output values. Conditions can use fields such as account, service, resource name, Kubernetes namespace, imported dimensions, or another virtual dimension.

    <Frame>
      <img alt="Virtual dimension rules editor with conditions and output value mapping" />
    </Frame>
  </Step>

  <Step title="Order the rules">
    Rules are evaluated from top to bottom. Drag rules into the priority order you want.
  </Step>

  <Step title="Save">
    Costory reprocesses historical data and makes the new values available across the product.
  </Step>
</Steps>

Every virtual dimension ends with a **leftover bucket**: a catch-all value for any cost row that matches none of your rules. Watch its share when you build rules: a large leftover usually means a rule is missing or too narrow.

## Explore and build allocation with your AI assistant

Most of the work in allocation is deciding which field to split on, not entering the rules. Through the [Costory FinOps MCP](/features/mcp), an assistant runs that exploration against your real spend and turns the result into a published dimension from chat. Before any rule exists, it can:

* Surface the values behind a concept with semantic search. Ask for "checkout" and you also get `payment-api`, `order-service`, and `cart-backend`, so one rule covers related spend a literal match would miss.
* Test which field best separates your cost with group-by suggestions and ad-hoc queries, so you split on something meaningful instead of guessing.
* Preview where the money lands. A per-rule preview shows trailing-30-day cost per bucket and the leftover share, so a missing or too-narrow rule is obvious before you publish.
* Flag rules that overlap. The overlap matrix shows when a broad early rule shadows a later one and swallows its spend.

Creating the dimension is the easy last step. The assistant drafts the rules as CEL conditions (top to bottom, first match wins), adds the leftover bucket automatically, and keeps everything on a **draft**. Publishing is explicit and triggers a data refresh, so production stays unchanged until you confirm.

<Tip>
  Describe the outcome you want ("split our shared Cloud SQL bill across teams by schema size") and let the assistant explore the data and propose rules. Review the preview, especially the leftover share, before approving the publish.
</Tip>

See the [FinOps MCP reference](/features/mcp#virtual-dimensions) for the underlying tools and parameters.

## Reallocate shared cost with a usage metric

Beyond mapping rows to fixed values, a virtual dimension rule can split a shared cost **proportionally** across teams based on a synced usage metric, a **telemetry** allocation. For example, divide a shared Cloud SQL bill across teams by each schema's size instead of guessing a flat percentage.

Connect a metric source from **Integrations** > **+ Add integration** > **External metric** ([Metrics Correlation](/setup/usage-metrics)), then add the allocation rule from the web app or through MCP. See [Shared Cost Allocation](/features/tagging/shared-cost-allocation) for the full walkthrough and supported sources.

## Dimension sources

| Source                 | Examples                                        | When to use                                                                                             |
| ---------------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| Native tags and labels | `env`, `aws:Environment`, `project.labels.team` | You already tag resources, but names or values differ by provider                                       |
| Standard columns       | Provider, account, service, region, namespace   | You need allocation from billing metadata that is always present                                        |
| Other dimensions       | `environment`, `team`, `business_unit`          | You want a hierarchy, such as namespace -> team -> business unit                                        |
| Usage metrics          | Database size, API calls, CPU time              | You need [shared cost allocation](/features/tagging/shared-cost-allocation) based on actual consumption |

## Common patterns

### Environment dimension

Merge `env`, `environment`, and `k8s_label_env`, then normalize values into `development`, `staging`, and `production`. Use this for environment cost reports and alerts.

### Team virtual dimension

Map accounts, namespaces, services, and project IDs to teams. This helps you allocate untagged resources and create team scopes in [Teams](/features/teams).

### Allocation hierarchy

Build one dimension on top of another. For example:

```mermaid theme={null}
graph LR
    A[Kubernetes namespace] --> B[Team]
    B --> C[Business unit]
    C --> D[P&L line]
```

When the team mapping changes, every dashboard, alert, and report that uses the downstream dimensions updates after reprocessing.

## Next Steps

<CardGroup>
  <Card title="Tag & Allocate overview" icon="tags" href="/features/tagging">
    See how dimensions and shared cost allocation fit together
  </Card>

  <Card title="Shared Cost Allocation" icon="chart-pie" href="/features/tagging/shared-cost-allocation">
    Split shared infrastructure costs with usage metrics
  </Card>

  <Card title="Explorer" icon="magnifying-glass" href="/features/cost-explorer">
    Use dimensions to filter and group cost data
  </Card>

  <Card title="Automated Environment Visibility" icon="eye" href="/use-cases/automated_env_allocation/visibility">
    Walk through an environment dimension example
  </Card>

  <Card title="Explore allocation with AI (MCP)" icon="robot" href="/features/mcp#virtual-dimensions">
    Explore your spend and build virtual dimensions from chat
  </Card>
</CardGroup>


# Split Shared Infrastructure Costs Across Teams
Source: https://docs.costory.io/features/tagging/shared-cost-allocation

Allocate shared cloud infrastructure costs like Cloud SQL, RDS, or network to teams based on actual usage metrics from any External metric source: Datadog, Datadog CI Visibility, Amplitude, BigQuery, Google Sheets, Tsuga, CloudWatch, S3, Snowflake, or Custom metrics.

A shared Cloud SQL database that costs $10K/month rarely splits evenly across the teams that use it. Instead of a flat 50/50 guess, Costory allocates `$7K`to Team A and`\$3K\` to Team B based on actual database usage from Datadog. Connect any usage metric, and Costory splits the cost proportionally, with no manual percentages to maintain.

<Frame>
  <img alt="Pie chart showing database cost split proportionally across three teams based on usage" />
</Frame>

## Key terms

* **Shared cost allocation**: The process of distributing a shared infrastructure cost across the teams or services that consume it, proportionally based on usage.
* **Usage metric**: An external measurement (e.g., database size per schema, CPU time per user, API calls per team) used to determine each team's share of a shared cost.
* **Virtual dimension**: A rule-based cost grouping. Shared cost allocation is configured as a special type of virtual dimension rule. See [Dimensions](/features/tagging/dimensions#virtual-dimensions).

See the [Glossary](/docs/glossary) for a full list of terms.

## Supported metric sources

Costory can use usage metrics from several data sources to drive proportional cost allocation.

<CardGroup>
  <Card title="Datadog" icon="dog" href="/setup/usage-metrics/datadog" />

  <Card title="Datadog CI Visibility" icon="code-branch" href="/setup/usage-metrics/datadog-ci" />

  <Card title="BigQuery" icon="database" href="/setup/usage-metrics/bigquery" />

  <Card title="Tsuga" icon="chart-mixed" href="/setup/usage-metrics/tsuga" />

  <Card title="AWS CloudWatch" icon="chart-line" href="/setup/usage-metrics/aws-cloudwatch" />

  <Card title="S3 metrics" icon="box" href="/setup/usage-metrics/s3-parquet" />

  <Card title="Amplitude" icon="chart-simple" href="/setup/usage-metrics/amplitude" />

  <Card title="Google Sheets" icon="table" href="/setup/usage-metrics/google-sheet" />

  <Card title="Snowflake" icon="database" href="/setup/usage-metrics/snowflake" />

  <Card title="Custom metrics" icon="plug" href="/setup/usage-metrics/custom-metrics-push" />
</CardGroup>

Connect your metric source from **Integrations** > **+ Add integration** > **External metric**. See [Metrics Correlation](/setup/usage-metrics), then reference it in a [<Tooltip href="/docs/glossary#virtual-dimensions">virtual dimension</Tooltip>](/features/tagging/dimensions#virtual-dimensions) rule.

## How it works

<Steps>
  <Step title="Connect a usage metric source">
    Go to [Integrations](https://app.costory.io/integration), click **+ Add integration**, then under **External metric** connect a source from the grid above. See [Metrics Correlation](/setup/usage-metrics) for details.&#x20;
  </Step>

  <Step title="Create or edit a virtual dimension">
    Open the virtual dimension where you want to add shared cost allocation, for example `Team`. See [Dimensions](/features/tagging/dimensions#virtual-dimensions) if you haven't created one yet.
  </Step>

  <Step title="Add a metric-based rule">
    Select the usage metric you connected. Costory will use the metric's values to determine each team's proportional share of the cost.
  </Step>

  <Step title="Map metric dimensions to teams">
    Tell Costory how metric labels correspond to team names. Three mapping types are available (see below).
  </Step>

  <Step title="Apply">
    Costory reprocesses your data. The shared cost is split proportionally and appears in [Explorer](/features/cost-explorer) grouped by team.
  </Step>
</Steps>

## Mapping metric labels to teams

When a usage metric has dimension labels (e.g., a `schema` label per database schema), you need to map those labels to the team names in your virtual dimension.

| Mapping type | How it works                                                           | When to use                                                                          |
| ------------ | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| **Identity** | The metric label already matches the team name exactly                 | Your metric labels and team names are the same (e.g., `payments` in both)            |
| **Regex**    | Extract the team name from the metric label using a regular expression | Labels follow a pattern like `team-payments-prod` and you need to extract `payments` |
| **Manual**   | Explicitly assign each metric label to a team                          | Labels don't follow a pattern, or you need full control over the mapping             |

## Common allocation patterns

Shared cost allocation works well for:

* Shared databases (Cloud SQL, RDS, Aurora), split by schema size, query count, or connection time per team
* Network and egress costs, split by traffic volume per namespace or service
* Shared Kubernetes clusters, split by CPU or memory usage per namespace. See [EKS cost allocation](/use-cases/eks-cost-allocation) for a full example.
* Third-party API costs, split by API call count per team. See [Reallocate API Costs](/use-cases/reallocate_api_costs) for a walkthrough.
* Support and licensing fees, split proportionally based on each team's share of total spend

## Automate reporting

Once costs are allocated, you can automate weekly reports per team via [Cost Reports](/features/slack-reports). Each team sees their share of shared infrastructure alongside their direct costs, all in one place.

<Note>
  For a step-by-step walkthrough, see [Allocate a shared Cloud SQL database](/use-cases/allocate_shared_cloud_sql_database/allocate).
</Note>

## Next Steps

<CardGroup>
  <Card title="Dimensions" icon="layer-group" href="/features/tagging/dimensions">
    Build imported and rule-based dimensions
  </Card>

  <Card title="Allocate a Shared Database" icon="database" href="/use-cases/allocate_shared_cloud_sql_database/allocate">
    Step-by-step: split a Cloud SQL bill across teams
  </Card>

  <Card title="Reallocate API Costs" icon="arrow-right-arrow-left" href="/use-cases/reallocate_api_costs">
    Split shared API costs using an external usage metric
  </Card>

  <Card title="Metrics Correlation" icon="gear" href="/setup/usage-metrics">
    Connect any External metric source
  </Card>
</CardGroup>


# Teams
Source: https://docs.costory.io/features/teams

Scope cloud costs, default metrics, and dashboards per team so every stakeholder sees the data that matters to them.

A single cost view rarely works for an entire organization. Your backend squad needs <Tooltip href="/docs/glossary#savings-plans">Contracted Cost</Tooltip> scoped to their services, while finance needs Billed Cost across everything. **Teams** let you configure those defaults once so each group lands on the right numbers without manual filtering.

<Frame>
  <img alt="Setting up a team and assigning a cost scope in Costory" />
</Frame>

## Overview

A Team is a group of users that share three things: a default cost metric (Contracted, Effective, or Billed) applied across all screens, one or more cost scopes that pre-filter every view to the team's perimeter, and a set of dashboards and saved views that all members can edit together. Dashboards can be public (visible org-wide) or private (team members only).

If you are looking for where Teams and other admin pages live in the app, see [Settings](/get-started/settings). To invite someone to the Costory organization first, click the **account name** in the left sidebar and open **Invites**. This is available to **Admin** users. After they join, add them to a team.

<Info>
  When a user belongs to multiple teams, the first team they were added to provides the default scope.
</Info>

## Get started

<Steps>
  <Step title="Create a team">
    <Tabs>
      <Tab title="UI">
        Navigate to **Settings > Teams** and click **Create Team**. Give the team a name, an optional description, and choose its visibility.

        <Frame>
          <img alt="Creating a new team in Costory" />
        </Frame>
      </Tab>

      <Tab title="Terraform">
        ```hcl theme={null}
        terraform {
          required_providers {
            costory = {
              source  = "costory-io/costory"
              version = ">= 0.1.0"
            }
          }
        }

        variable "costory_api_token" {
          type        = string
          description = "Costory API token."
          sensitive   = true
        }

        provider "costory" {
          token = var.costory_api_token
        }

        # Public team
        resource "costory_team" "engineering" {
          name        = "Engineering"
          description = "All engineering members"
          visibility  = "PUBLIC"
        }
        ```

        ```hcl theme={null}
        terraform {
          required_providers {
            costory = {
              source  = "costory-io/costory"
              version = ">= 0.1.0"
            }
          }
        }

        variable "costory_api_token" {
          type        = string
          description = "Costory API token."
          sensitive   = true
        }

        provider "costory" {
          token = var.costory_api_token
        }

        # Public team
        resource "costory_team" "engineering" {
          name        = "Engineering"
          description = "All engineering members"
          visibility  = "PUBLIC"
        }
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="Add members">
    <Tabs>
      <Tab title="UI">
        Open your team in **Settings > Teams** and click **Add member**. Invite members by email and assign each person a role.

        <Frame>
          <img alt="Data team detail page in Costory showing two members with Owner and Member roles, PUBLIC visibility, and Contracted Cost as the default metric" />
        </Frame>

        | Role       | Permissions                                           |
        | ---------- | ----------------------------------------------------- |
        | **Owner**  | Add/remove members, manage scopes, edit team settings |
        | **Member** | Use team scopes, view and edit team dashboards        |
      </Tab>

      <Tab title="Terraform">
        ```hcl theme={null}
        terraform {
          required_providers {
            costory = {
              source  = "costory-io/costory"
              version = ">= 0.1.0"
            }
          }
        }

        variable "costory_api_token" {
          type        = string
          description = "Costory API token."
          sensitive   = true
        }

        provider "costory" {
          token = var.costory_api_token
        }

        resource "costory_team" "engineering" {
          name       = "Engineering"
          visibility = "PRIVATE"
        }

        variable "team_members" {
          type = map(object({
            email = string
            role  = string
          }))
          default = {
            alice = { email = "alice@example.com", role = "OWNER" }
            bob   = { email = "bob@example.com", role = "MEMBER" }
            carol = { email = "carol@example.com", role = "MEMBER" }
          }
        }

        resource "costory_team_member" "members" {
          for_each = var.team_members

          team_id = costory_team.engineering.id
          email   = each.value.email
          role    = each.value.role
        }
        ```

        ```hcl theme={null}
        terraform {
          required_providers {
            costory = {
              source  = "costory-io/costory"
              version = ">= 0.1.0"
            }
          }
        }

        variable "costory_api_token" {
          type        = string
          description = "Costory API token."
          sensitive   = true
        }

        provider "costory" {
          token = var.costory_api_token
        }

        resource "costory_team" "engineering" {
          name       = "Engineering"
          visibility = "PRIVATE"
        }

        variable "team_members" {
          type = map(object({
            email = string
            role  = string
          }))
          default = {
            alice = { email = "alice@example.com", role = "OWNER" }
            bob   = { email = "bob@example.com", role = "MEMBER" }
            carol = { email = "carol@example.com", role = "MEMBER" }
          }
        }

        resource "costory_team_member" "members" {
          for_each = var.team_members

          team_id = costory_team.engineering.id
          email   = each.value.email
          role    = each.value.role
        }
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="Assign cost scopes">
    Scopes are persistent filters that apply by default whenever a team member opens [Explorer](/features/cost-explorer), a dashboard, or any cost view. They define the team's cost boundary: for example, only the AWS accounts or GCP projects the team owns.

    <Frame>
      <img alt="Explorer with a team scope 'ML stack' applied as a persistent filter in the Where clause" />
    </Frame>

    To add a scope:

    1. Go to **Settings > Teams** and select your team.
    2. Click **Add Scope** and define the filter conditions.
    3. Save. The scope applies by default to every view for all team members.

    You can assign multiple scopes per team, for example one for compute resources and another for storage.

    <Tip>
      Team members can temporarily remove a scope to see organization-wide costs. The scope is re-applied automatically when they open a new view.
    </Tip>
  </Step>
</Steps>

## Key capabilities

### Default cost metric per team

Different stakeholders need different [cost metrics](/docs/cost-metrics). With Teams, you set the default once and it applies across Explorer, dashboards, and Digest.

Engineering teams typically default to <Tooltip href="/docs/glossary#savings-plans">Contracted Cost</Tooltip>, which is stable and reflects actual resource usage without [Savings Plan fluctuations](/docs/savings-plan-cost-fluctuation). Finance teams prefer Effective Cost or Billed Cost, which reflects what is actually invoiced.

Individual users can still switch metrics on the fly. For a guide on matching metrics to personas, see [Cost Metrics Per Persona](/use-cases/show_the_correct_cost_metric_to_each_persona).

### Persistent cost scopes

Common scope patterns include scoping by AWS account or GCP project to match the team's ownership, by cloud service (e.g., SageMaker, BigQuery), by <Tooltip href="/docs/glossary#dimensions">dimension</Tooltip> such as `team = ML` using [Dimensions](/features/tagging/dimensions), or by Kubernetes namespace.

### Shared dashboards and views

Assign dashboards and saved views to a team so all members can collaborate. Public dashboards are visible to the entire organization, which is useful for cross-team cost overviews. Private dashboards are restricted to team members for team-specific analysis.

<Frame>
  <img alt="Costory dashboard owned by the Data team showing description, team ownership, labels, and the ML stack scope" />
</Frame>

All team members can edit dashboards assigned to their team. People outside the team can view public dashboards but cannot edit them.

## Manage teams

### Edit a team

Open **Settings > Teams** and select the team you want to modify. From there you can rename the team, update its description, change its visibility (Public or Private), and update the default cost metric.

In Terraform, update the corresponding `costory_team` resource attributes and run `terraform apply`.

### Delete a team

Open **Settings > Teams**, select the team, and click **Delete Team**. Deleting a team removes all scopes and unlinks all dashboards. Members are not deleted from Costory, they just lose access to the team's private dashboards.

<Warning>
  Deleting a team cannot be undone. Make sure to reassign any dashboards you want to keep before deleting.
</Warning>

In Terraform, remove the `costory_team` resource from your configuration and run `terraform apply`.

### Roles and permissions

| Role       | Members        | Scopes               | Team settings                                      | Dashboards               |
| ---------- | -------------- | -------------------- | -------------------------------------------------- | ------------------------ |
| **Owner**  | Add and remove | Create, edit, delete | Edit name, description, visibility, default metric | Edit all team dashboards |
| **Member** | View only      | View only            | View only                                          | Edit all team dashboards |

Owners have full control over the team configuration. Members can use the team's scopes and edit dashboards assigned to the team, but cannot change membership or settings. Both roles can temporarily remove a scope to see organization-wide costs.

## Frequently Asked Questions

<AccordionGroup>
  <Accordion title="What happens when a user belongs to multiple teams?">
    The first team the user was added to provides the default scope. The user can still access dashboards and scopes from all their teams.
  </Accordion>

  <Accordion title="Can team members remove a scope temporarily?">
    Yes. Scopes apply by default, but any team member can remove the scope filter to see organization-wide costs. The scope is re-applied when they navigate to a new view.
  </Accordion>

  <Accordion title="Do Cost Reports inherit team scopes?">
    Team scopes are applied when a team member creates a [Cost Report](/features/slack-reports) or a saved View. Alerts and scheduled reports cannot be owned by a team yet, so they are managed per user.
  </Accordion>

  <Accordion title="What is the difference between PUBLIC and PRIVATE visibility?">
    A **Public** team's dashboards are visible to everyone in the organization. A **Private** team's dashboards are only visible to team members. In both cases, only team members can edit the team's dashboards.
  </Accordion>

  <Accordion title="Can I manage team scopes via Terraform?">
    Not yet. Scopes are currently managed through the UI. Team creation and member assignment are available via the [Costory Terraform provider](#create-a-team).
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup>
  <Card title="Settings" icon="gear" href="/get-started/settings">
    Find Teams, Data Integrations, API Keys, and Plan & Invoices.
  </Card>

  <Card title="Explorer" icon="magnifying-glass" href="/features/cost-explorer">
    Explore your costs with team scopes applied by default
  </Card>

  <Card title="Tag & Allocate Costs" icon="tags" href="/features/tagging">
    Build the dimensions that power your team scopes
  </Card>

  <Card title="Cost Metrics Per Persona" icon="users" href="/use-cases/show_the_correct_cost_metric_to_each_persona">
    Match the right cost metric to each stakeholder
  </Card>

  <Card title="Cost Metrics Reference" icon="calculator" href="/docs/cost-metrics">
    Understand Contracted, Effective, and Billed costs
  </Card>
</CardGroup>


# Unit Economics
Source: https://docs.costory.io/features/unit-economics

Build cloud unit economics in Costory Explorer by combining cloud cost metrics, usage metrics, and formulas such as cost per user, cost per API call, or ROI.

<Tooltip href="/docs/glossary#unit-economics">Unit economics</Tooltip> turns cloud spend into efficiency metrics. Use it when total cost is rising and you need to know whether cost per user, transaction, request, or workload is improving.

<Frame>
  <img alt="Dashboard showing total cloud spend increasing while cost per client decreases" />
</Frame>

## Overview

Costory Explorer lets you combine cost metrics, usage metrics, and formulas in the same chart. Instead of stopping at "compute spend increased", you can track "cost per active user decreased" or "cost per transaction crossed our target".

Use unit economics when you need to:

* Explain cloud cost increases in the context of business growth
* Track cost per customer, API call, transaction, build minute, or container-hour
* Compare efficiency by team, service, region, or product
* Report engineering improvements in the same terms finance and leadership use

## What you can build

* Track infrastructure ratios such as cost per GB transferred, build minute, or container-hour by dividing cloud spend by usage metrics from your billing data or Datadog.
* Track application ratios such as cost per API call, daily active user, or transaction by connecting an [external metric](/setup/usage-metrics) from Datadog, Datadog CI Visibility, Amplitude, BigQuery, [Cloud Monitoring](/setup/usage-metrics/gcp-cloud-monitoring), Google Sheets, Tsuga, CloudWatch, S3, Snowflake, or [Custom metrics](/setup/usage-metrics/custom-metrics-push).
* Compare the cost of a new service against the service it replaced by grouping formulas by service tag.
* Track realized savings from <Tooltip href="/docs/glossary#savings-plans">Savings Plans</Tooltip> or CUDs by computing `list_cost - total_cost`.
* Build custom KPIs for commitment utilization, coverage, and ROI.

You can apply these patterns to [hourly granularity for bursty workloads](/use-cases/hourly-cost-granularity), [BigQuery cost visibility with dbt](/use-cases/dbt_bigquery_visibility/increase_visibility), or [allocating shared database costs](/use-cases/allocate_shared_cloud_sql_database/allocate).

## Metric types

Costory's query bar supports the metric types you need for formulas.

<Tabs>
  <Tab title="Cost metrics">
    Built-in billing metrics from your connected cloud providers. These include total cost, <Tooltip href="/docs/glossary#contracted-cost">Contracted Cost</Tooltip>, list cost, and usage quantity.
  </Tab>

  <Tab title="Usage metrics">
    Cloud provider usage metrics such as GB-Hours, ReadCapacityUnit-Hrs, and vCPU-Hours. These come from your billing data and describe how much of a resource you consumed.

    <Frame>
      <img alt="Selecting GB-Hours as a usage metric to calculate per-unit storage cost in Explorer" />
    </Frame>
  </Tab>

  <Tab title="External metrics">
    Metrics from sources you connect under **Integrations** > **+ Add integration** > **External metric**: Datadog, Datadog CI Visibility, Amplitude, BigQuery, Google Sheets, Tsuga, CloudWatch, S3, Snowflake, or [Custom metrics](/setup/usage-metrics/custom-metrics-push). These describe business or application activity that you correlate with cloud cost. Query them in **Advanced Explorer** only. Classic greys out non-cost metrics.

    <Frame>
      <img alt="Advanced Explorer metric picker open on Cost, with integrations listing Tsuga and BigQuery" />
    </Frame>
  </Tab>
</Tabs>

## Prerequisites

To build formulas from business or application activity, connect at least one [external metrics source](/setup/usage-metrics) from **Integrations** > **+ Add integration** > **External metric**. Supported sources include:

* [Datadog](/setup/usage-metrics/datadog) for infrastructure and application metrics
* [Datadog CI Visibility](/setup/usage-metrics/datadog-ci) for pipeline metrics
* [Amplitude](/setup/usage-metrics/amplitude) for product analytics such as DAU, MAU, and sessions
* [BigQuery](/setup/usage-metrics/bigquery) for warehouse-native metrics
* [Google Sheets](/setup/usage-metrics/google-sheet) for numeric columns from a spreadsheet
* [Tsuga](/setup/usage-metrics/tsuga) for live cluster metrics, logs, and traces
* [AWS CloudWatch](/setup/usage-metrics/aws-cloudwatch) for CloudWatch metrics
* [S3 metrics](/setup/usage-metrics/s3-parquet) for Parquet files in S3
* [Snowflake](/setup/usage-metrics/snowflake) for tables in a granted database
* [Custom metrics](/setup/usage-metrics/custom-metrics-push) for hourly points you POST yourself

<Info>
  You can still use formulas without external metrics. Combine cost fields with usage metrics from billing data, such as cost per GB-Hour, without connecting another source.
</Info>

## Create a unit economics formula

<Steps>
  <Step title="Open Advanced Explorer">
    Click **Explore your data**, switch **Classic** to **Advanced**, and configure the cost query you want to analyze. Classic greys out non-cost metrics. See [Explorer](/features/cost-explorer).
  </Step>

  <Step title="Add metrics">
    Click **+ Add Metric** in the query bar to add a cost metric, usage metric, or external metric. Use the **integrations** chip for sources you connected under **External metric**. Each metric gets a letter label that you reference in formulas.
  </Step>

  <Step title="Add a formula">
    Click **+ Add Formula** and write your formula with the metric labels.

    Examples:

    * If metric **a** is total cost and metric **b** is GB-Hours, `a / b` gives you cost per GB-Hour.
    * If metric **a** is total cost and metric **b** is Daily Active Users, `a / b` gives you cost per DAU.

    <Frame>
      <img alt="Formula editor combining total cost divided by usage metric to produce cost per unit over time" />
    </Frame>

    <Note>
      Formulas support `+`, `-`, `*`, `/`, and parentheses. For rolling averages or conditional logic, pre-compute the metric in your source system before you connect it.
    </Note>
  </Step>

  <Step title="Visualize the result">
    The chart updates to show the formula over time. Switch chart types and toggle between raw metrics and the formula output.

    <Frame>
      <img alt="Cost per DAU trending down while total cloud spend increases" />
    </Frame>
  </Step>

  <Step title="Save and share">
    Save the query as a [dashboard widget](/features/dashboards/create-dashboard) so you can revisit it, share it with [Quick Share](/features/dashboards/quickshare), or schedule it as a [Cost Report](/features/slack-reports).
  </Step>
</Steps>

<Tip>
  Formulas respect your group-by dimensions. If you group by team and define `cost / daily_active_users`, Costory returns a separate cost-per-DAU value for each team.
</Tip>

<Tip>
  You can ask the [Costory MCP](/features/mcp) to build the ratio for you: *"show cost per active user this quarter, broken down by service."* It picks the right usage metric and returns the result you can save as a widget.
</Tip>

<Tip>
  You can set threshold alerts on any formula. If cost per request exceeds your target, Costory sends a notification through Slack or email. Configure thresholds in [cloud cost alerts](/features/alerts).
</Tip>

## Frequently asked questions

<AccordionGroup>
  <Accordion title="How do I track cloud cost per user or per transaction?">
    Connect a usage metric such as DAU from Amplitude or transactions from your database. In Explorer, create a formula that divides cloud spend by that metric. For a full walkthrough, see [cost per active user with Amplitude](/use-cases/amplitude/cost_per_active_users).
  </Accordion>

  <Accordion title="Do formulas work with group-by dimensions?">
    Yes. If you group by a dimension such as team or service, the formula is applied per group. This lets you compare unit economics across teams, services, or products.
  </Accordion>

  <Accordion title="What operators can I use in formulas?">
    Formulas support arithmetic operators (`+`, `-`, `*`, `/`) and parentheses. Each metric is referenced by its letter label. Formulas operate on the aggregated value per time bucket.
  </Accordion>

  <Accordion title="Can I alert on a unit economics metric?">
    Yes. Save the formula and create an alert from it. Use this for targets such as cost per request, cost per active user, or cost per build minute.
  </Accordion>
</AccordionGroup>

## Related links

<CardGroup>
  <Card title="Explorer" icon="magnifying-glass" href="/features/cost-explorer">
    Build the base cost queries for unit economics.
  </Card>

  <Card title="Metrics Correlation" icon="chart-line" href="/setup/usage-metrics">
    Connect external metrics from Integrations.
  </Card>

  <Card title="Events" icon="calendar-days" href="/features/events">
    Add timeline context to cost changes.
  </Card>

  <Card title="Cost per active user" icon="users" href="/use-cases/amplitude/cost_per_active_users">
    Follow a worked example with Amplitude.
  </Card>
</CardGroup>


# Quickstart: How to set up automated cloud cost reporting in 30 minutes
Source: https://docs.costory.io/get-started/quickstart

Step-by-step guide to connect AWS, GCP, Azure and Datadog to Costory. Set up automated FinOps Slack & Teams cost reports in 30 minutes, free trial included.

New to Costory? Read the [Welcome](/get-started/welcome) page for how the product fits DevOps workflows, then follow the steps below.

<Frame>
  <img alt="Example of weekly cost reporting message sent by Costory" />
</Frame>

Here's what you can expect in 30 minutes:

* Set up your 14-day free trial with your cloud billing data connected.
* Get a unified view of your costs across teams, providers, and environments.
* Receive your first Costory report in your team's inbox (Slack, Teams, or email).

## Prerequisites for Costory cloud cost management setup

* **Cloud billing admin access**: Be a billing admin on your cloud provider account. Marketplace admins can also purchase Costory from the marketplace at the end of onboarding.
* **Slack or Teams app install**: Have your Slack or Teams admin ready to install the Costory app, or hold admin permissions yourself.

## Step 1: Connect your AWS, GCP, Azure billing accounts (10 minutes)

<Steps>
  <Step title="Create your Costory Account: 1 minute">
    <Card title="Sign up for Costory" icon="rocket" href="https://app.costory.io/sign-up">
      Request a free trial
    </Card>
  </Step>

  <Step title="Connect your cloud billing data: 10 minutes">
    Go to [Setup Billing Datasources](https://app.costory.io/datasources/billing)

    <Tabs>
      <Tab title="AWS CUR using CloudFormation">
        <Frame>
          <img alt="Setup AWS CUR using CloudFormation Template" />
        </Frame>

        <Check>If you have an existing export, you will be able to import it directly in Costory. </Check>

        <Check> If you need to create a new report, AWS takes between 6 and 12 hours to export the first file. And 12-24 hours to backfill the historical data. Costory will ping you when your data is ready.</Check>
      </Tab>

      <Tab title="GCP Billing Export">
        Click new datasource and select GCP. You will see your Costory service account email. Share your BigQuery dataset with it using these IAM roles: BigQuery Data Viewer and BigQuery Metadata Viewer.

        <Check>The data will be available in Costory within 10 minutes.</Check>
      </Tab>

      <Tab title="Azure Billing Export">
        <Frame>
          <img alt="Azure setup" />
        </Frame>

        <Check>
          If you have an existing export, you will be able to import it directly in Costory.
        </Check>

        <Check>
          If you need to create a new report, Azure takes between 5 and 10 minutes to export the first file. You can then trigger backfills (\~1 hour).
        </Check>
      </Tab>

      <Tab title="Datadog">
        <Frame>
          <img alt="Datadog setup" />
        </Frame>

        <Check>The data will be available in Costory within 10 minutes.</Check>
      </Tab>
    </Tabs>
  </Step>

  <Step title="Wait for your data to be ingested: (from 10 minutes to 24 hours depending on your luck but mostly on your provider...)">
    Costory will ingest your data and make it available.
    Depending on your provider, the first export may take from 10 minutes (GCP, Azure) to several hours (AWS).
  </Step>
</Steps>

## Step 2: Automate your cloud cost reporting (20 minutes)

<Steps>
  <Step title="Create Dimensions: Costory automatically finds your best labels: 5 minutes">
    Costory will read your existing labels across providers, suggest merges and mappings to standardize keys and values.

    Going from 3 labels: `env`, `environment`, `k8s_label_env` with many different values to a single label: `environment`, with only 3 values: `development`, `staging`, `production`.

    You can review those in the [Dimensions page](https://app.costory.io/dimensions), and add more transformations to your labels:

    <Frame>
      <img alt="Dimensions UI showing label values being remapped into a clean dimension" />
    </Frame>

    <Check>
      Dimensions keep Explorer clean with only the
      meaningful labels and values. They also help our AI assistant better
      understand your data and keep its explanations clear and actionable.
    </Check>
  </Step>

  <Step title="Verify Billing Data: 5 minutes">
    Explore the cost using Last Month date preset, or Last invoice month (uses invoice date instead of usage dates).

    <Frame>
      <img alt="Costory Explorer showing last month billing data with cost breakdown, cost distribution, and comparison details" />
    </Frame>

    Check that the amounts are correct. Trust the data before building reports on top of it.

    Useful docs:

    * [Standard Columns](/docs/standard-columns): how we normalize raw exports into columns.
    * [Cost Metrics](/docs/cost-metrics): the metrics we compute on top of your data.
    * [Currency conversion](/docs/currency-conversion): how we convert into your reporting currency.
  </Step>

  <Step title="Deploy FinOps Dashboards & Alerts: 10 minutes">
    Start from template dashboards instead of building from scratch. Costory templates cover the most common FinOps scenarios, and Costory suggests relevant ones for you.

    <Frame>
      <img alt="Costory dashboard showing FinOps widgets that can be saved and shared with your team" />
    </Frame>

    [Dashboards](https://app.costory.io/dashboards/new) cover Kubernetes cost and waste, EC2 and Savings Plan coverage, network costs, realized savings, and more.

    If you connect [Costory MCP](/features/mcp), you can also skip the blank canvas: ask Claude or Cursor to "build a dashboard for Kubernetes cost by namespace" and it drafts the widgets for you.

    Alert templates notify you when:

    * The cost of your R\&D environment is above your production costs.
    * The data scientists started two VMs with huge GPU during the week-end.
    * Reserved instances are not fully used.
    * Your savings plan no longer covers 50% of your costs.
    * A mandatory tag is no longer attached to most of your costs.
    * Your K8S waste ratio is above 75%.

    <Frame>
      <img alt="Costory alerts page listing active cost alerts for savings plan coverage, Kubernetes waste, and weekly cost changes" />
    </Frame>
  </Step>

  <Step title="Automate Slack and Teams Cost Reports: Share costs with your team: 5 minutes">
    Teams own cloud costs once they can see them.

    Share a weekly and a monthly report via Slack, Teams, or email. You can share any view:

    * [Cost per environment](/use-cases/automated_env_allocation/visibility)
    * Service name with cost changes over the last week.
    * [Monthly cost per daily active users](/use-cases/amplitude/cost_per_active_users)

      <Frame>
        <img alt="Costory report builder showing a cost per service report configured for recurring delivery" />
      </Frame>

    <Frame>
      <img alt="Example of weekly cost reporting message sent by Costory" />
    </Frame>

    Connect easily with your team. We support:

    <Tabs>
      <Tab title="Slack">
        Go to [Integrations](https://app.costory.io/integration/). Connect the Costory App to your Slack.

        <Frame>
          <img alt="Slack authorization flow for installing the Costory app in a workspace" />
        </Frame>
      </Tab>

      <Tab title="Teams">
        Go to [Integrations](https://app.costory.io/integration/). Download the zip from Integrations, then upload it in Teams Admin Center > Manage Apps
      </Tab>

      <Tab title="Email">
        No setup required, you can use it right away.
      </Tab>
    </Tabs>
  </Step>
</Steps>

## Next Steps

Here's what most of our customers do in their first week:

* Invite teammates: click the **account name** in the left sidebar, then **Invites** (Admins). See [Settings](/get-started/settings#invite-users).
* Set up alerts: [check our templates](https://app.costory.io/alerts/new)
* [Calculate your cost per environment](/use-cases/automated_env_allocation/visibility)
* [Show the correct metrics to your exec team](/use-cases/what_your_exec_team_wants/value)
* [Connect a business metric to understand your marginal costs](/use-cases/amplitude/cost_per_active_users).

### Need help?

We're here to help. Reach out to us at [support@costory.io](mailto:support@costory.io) or by Intercom in the bottom right corner of the app.


# Settings
Source: https://docs.costory.io/get-started/settings

Invite users as an Admin from the account name in the left sidebar. Find Costory settings, organization Invites, Teams, data integrations, API keys, plans, and invoices.

# Settings

Costory settings are split across personal account settings, organization settings, and Costory-managed settings. Use this page when you need to invite users, update login details, allow a company email domain, connect data, manage Teams, or review your plan and invoices.

Admin users invite teammates from the **account name** in the left sidebar, then **Invites**. Other Costory settings live in the menu next to your name. Some account and organization screens are hosted by Costory's authentication provider, since it controls sign-in, email addresses, passwords, connected accounts, and organization membership.

<Frame>
  <img alt="Costory user menu showing Teams, Data Integrations, Plan and Invoices, API Keys, and theme options" />
</Frame>

## Settings overview

| Settings area                  | Managed by              | Use it for                                                                                           | Where to find it                                                     |
| ------------------------------ | ----------------------- | ---------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
| Personal account settings      | Authentication provider | Change your profile, email address, password, and connected login accounts                           | User menu next to your name, then **Profile** or **Account**         |
| Organization identity settings | Authentication provider | Invite users and allow a verified company domain for automatic joining                               | Account name in the left sidebar, then **Invites**                   |
| Costory-managed settings       | Costory                 | Manage **Teams**, **Data Integrations**, **API Keys**, **Plan & Invoices**, and subscription details | User menu next to your name, then the relevant Costory settings page |

<Info>
  If a settings screen looks different from the rest of Costory, it is usually an authentication-provider screen. Changes made there still apply to your Costory account or organization.
</Info>

## Invite users

Only **Admin** users can invite people to your Costory organization. If you do not see **Invites**, ask an Admin to send the invitation or to grant you the Admin role.

<Steps>
  <Step title="Click the account name">
    In the left sidebar, click your **account name**. This is the organization name above your user profile.
  </Step>

  <Step title="Open Invites">
    Select **Invites** to open organization membership and pending invitations.
  </Step>

  <Step title="Send the invitation">
    Enter the person's email address and click **Invite**. They receive an email to join the organization.

    <Frame>
      <img alt="Costory organization Members screen with the Invitations tab, Invite button, and verified domain auto-join options" />
    </Frame>
  </Step>
</Steps>

You can also let people join without a manual invite by adding a verified company email domain. See [Identity and Access](/docs/sso-access-control) for auto-join, SSO, and SCIM.

<Note>
  Inviting someone to the organization is separate from adding them to a Costory **Team**. Teams control cost scopes and default metrics. Invite them here first, then add them in [Teams](/features/teams).
</Note>

## Personal account settings

Use personal account settings to manage your own sign-in details.

You can usually update:

* Profile name and avatar.
* Email addresses.
* Password, when password sign-in is enabled for your account.
* Connected accounts such as Google or Microsoft.

<Frame>
  <img alt="Personal account settings screen showing profile details, email addresses, and connected accounts" />
</Frame>

These settings affect your user account, not the full Costory organization. If you need to change how other users join, use **Invites** instead.

## Organization settings

Organization settings control who can access your Costory workspace.

Use organization settings to:

* Invite new users from **Invites**.
* Review existing members.
* Add a verified company email domain so users can join automatically.
* Manage domain-based access rules for your workspace.

For SSO, SCIM directory sync, domain auto-join, and identity-provider requirements, see [Identity and Access](/docs/sso-access-control).

## Costory-managed settings

Costory-managed settings control your FinOps workspace configuration.

| Page                  | Use it for                                                                  | Related docs                                                                                                                                                    |
| --------------------- | --------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Teams**             | Create teams, add members, set default cost metrics, and define team scopes | [Teams](/features/teams)                                                                                                                                        |
| **Data Integrations** | Connect billing data, usage metrics, collaboration tools, and event sources | [Billing Data](/setup/billing), [Metrics Correlation](/setup/usage-metrics), [Slack](/setup/collaboration/slack), [Microsoft Teams](/setup/collaboration/teams) |
| **API Keys**          | Create and rotate API keys for automation and external tools                | [MCP](/features/mcp), [Events API](/setup/events/custom-api), [Custom Metrics Push](/setup/usage-metrics/custom-metrics-push)                                   |
| **Plan & Invoices**   | Review your plan, subscription, billing contact, and invoices               | [Billing Data](/setup/billing)                                                                                                                                  |

<Warning>
  Treat API keys like passwords. Store them in a secret manager, rotate them when team access changes, and delete keys you no longer use.
</Warning>

## Common tasks

<Steps>
  <Step title="Invite a user">
    Click the **account name** in the left sidebar, open **Invites**, then send the invitation by email. This is available to **Admin** users.
  </Step>

  <Step title="Allow your company domain">
    Open **Invites** from the account name and add a verified domain. Users with that company email domain can join your Costory organization automatically when auto-join is enabled.
  </Step>

  <Step title="Create a Costory team">
    Open **Settings > Teams**, click **Create Team**, then add members and scopes. See [Teams](/features/teams) for the full setup.
  </Step>

  <Step title="Connect a data integration">
    Open **Data Integrations** from the user menu, then choose the provider you want to connect. Use [Billing Data](/setup/billing) for AWS, GCP, Azure, and other billing exports.
  </Step>

  <Step title="Review invoices or plan details">
    Open **Plan & Invoices** from the user menu to check your subscription, invoices, and billing details.
  </Step>
</Steps>

## Related pages

<CardGroup>
  <Card title="Identity and Access" icon="shield-keyhole" href="/docs/sso-access-control">
    Compare auto-join, SSO, SCIM, and identity-provider options.
  </Card>

  <Card title="Teams" icon="users" href="/features/teams">
    Configure team scopes, members, dashboards, and default cost metrics.
  </Card>

  <Card title="Billing Data" icon="database" href="/setup/billing">
    Connect cloud billing exports and monitor ingestion health.
  </Card>

  <Card title="Metrics Correlation" icon="chart-line" href="/setup/usage-metrics">
    Add business and observability metrics for unit economics.
  </Card>
</CardGroup>


# Welcome to Costory
Source: https://docs.costory.io/get-started/welcome

Cloud cost reporting for DevOps: connect AWS, GCP, and Azure billing, use Costory MCP with Claude or Cursor, and automate FinOps updates.

If you own infrastructure and get pulled into cost questions, you are in the right place. Costory is built for engineers who ship features and still answer "what changed on the bill?" without a dedicated [FinOps](/docs/glossary) team.

You might use Costory when:

* Finance or leadership asks for a monthly breakdown and you would rather not rebuild the same spreadsheet.
* Spend jumps and you need to know if it was a deploy, usage, or something the provider changed.
* You want teams to see their own numbers in Slack or Teams without you acting as a human report router.

You connect billing data from AWS, GCP, Azure, Datadog, [Elastic Cloud](/setup/billing/elastic-cloud), [Snowflake](/setup/billing/snowflake), and more. Costory normalizes it so you can explore, explain, and report without building your own data pipeline. In the first hour, you can also connect [Costory MCP](/features/mcp) to Claude or Cursor and investigate costs from chat.

<Frame>
  <img alt="Costory overview showing cloud cost exploration and dashboard workflows" />
</Frame>

## What you can stop doing

* Stop building and babysitting billing ETL just to get a unified view. Connect exports or APIs and Costory ingests line items. Start with [Billing data](/setup/billing).
* Stop running the monthly cost review by hand. Add a [Cost digest](/features/digest) to a [Cost Report](/v2/Automate/reports), tune the breakdown tree, and share Summary, Tree, or Table once it matches how your org talks about cost.
* Stop copy-pasting numbers into Slack or slides. [Cost Reports](/features/slack-reports) send each team the right view on a schedule.
* Stop guessing why spend moved. Correlate costs with deploys, incidents, and provider events in [Explorer](/features/cost-explorer), then add [Events](/features/events) and [Unit Economics](/features/unit-economics).
* Stop untangling the same tags in every console. Use [Dimensions](/features/tagging/dimensions) to clean labels and map costs to teams or environments.

## What Costory does

### See all your cloud costs in one place

Costory pulls billing data from your providers and normalizes it into a single view. No more switching between consoles or stitching exports by hand.

AWS, GCP, Azure, Datadog, Elastic Cloud, OpenAI, MongoDB, Confluent Cloud. Explore everything in one [Explorer](/features/cost-explorer).

### Understand why costs changed

<Frame>
  <img alt="Costory agent ties spend movements to causes you already care about" />
</Frame>

Costory ties spend movements to causes you already care about: GitHub deploys, Kubernetes signals, incidents, and provider events such as purchases.

When your bill moves, you can see whether it tracked a release, a usage spike, or a pricing change.

<AccordionGroup>
  <Accordion title="How correlation works">
    You always start by ingesting normalized billing into **Explorer**. Optionally, you connect event sources such as [GitHub](/setup/events/github), [CI/CD](/setup/events/ci-cd), or the [custom Events API](/setup/events/custom-api) so deploys, releases, and other signals appear as timeline markers. Those markers sit on the same time axis as your cost curves, so you can compare spend with what shipped or changed. See [Events](/features/events) and the [Events setup guides](/setup/events).
  </Accordion>
</AccordionGroup>

### Ask Claude or Cursor to investigate

[Costory MCP](/features/mcp) connects your Costory workspace to Claude, Cursor, VS Code, and other MCP-compatible assistants. Once billing data is connected, you can ask questions such as "what changed this week?", "which services should I group by?", or "prepare a dashboard for the data team."

Use the assistant to compare periods, find saved views, create alerts, send Cost Reports, and build the cost views that become dashboard widgets.

<iframe title="Costory MCP walkthrough in Claude and Cursor" />

### Get reports automatically, not manually

A [Cost digest](/features/digest) breaks monthly spend into a tree and surfaces ranked changes with draft summaries. You adjust the dimensions until the story matches your team, then schedule delivery to Slack or email and review Summary, Tree, or Table in Costory.

What used to take half a day to a full week can run on a schedule instead.

## Your first hour

<Steps>
  <Step title="Open the Quickstart">
    Create your trial and follow the guided path: [Quickstart: automated cloud cost reporting in 30 minutes](/get-started/quickstart). Check [Prerequisites](/get-started/quickstart#prerequisites-for-costory-cloud-cost-management-setup) so billing access and collaboration apps are lined up before you start.
  </Step>

  <Step title="Connect billing data">
    Link AWS, GCP, Azure, or other [billing datasources](/setup/billing). Costory uses **read-only** access to ingest exports or APIs. You do not manage warehouse schemas or sync jobs.
  </Step>

  <Step title="Connect Costory MCP">
    Add [Costory MCP](/features/mcp) to Claude Desktop, Claude Code, Cursor, VS Code, or Dust using `https://app-api.costory.io/mcp`. Authenticate with your Costory account, then ask your assistant to investigate the first cost spike, compare teams, or prepare dashboard views.
  </Step>

  <Step title="Get your first report out">
    Route a report to [Slack](/setup/collaboration/slack), [Teams](/setup/collaboration/teams), or email so your team sees value in the tools they already use.
  </Step>

  <Step title="Optional: organize and deepen">
    When you are ready, create [Dimensions](/features/tagging/dimensions), add rule-based virtual dimensions where tags are missing, and turn on the [Digest](/features/digest) for a structured monthly review.
  </Step>
</Steps>

## Start here

Costory starts with a **14-day free trial**. Pricing uses a **flat fee**, so your subscription stays predictable as your cloud bill changes. See [Costory pricing](https://www.costory.io/pricing).

**For security and platform reviewers:** Costory runs on **Google Cloud Platform (GCP)** with encryption **in transit and at rest**. Billing connections use **read-only** access to your exports or APIs. Review [Security](/docs/security), [Subprocessors](/docs/subprocessors), and [SSO and access control](/docs/sso-access-control).

<AccordionGroup>
  <Accordion title="More for security and platform reviewers">
    Users authenticate through **Clerk**, including OAuth with common identity providers. SSO, SCIM directory sync, and RBAC options are covered in [SSO and access control](/docs/sso-access-control). Customer data retention can be aligned with your policy. How read-only billing access works is described in [Billing data](/setup/billing).
  </Accordion>
</AccordionGroup>

### Week one

<CardGroup>
  <Card title="Quickstart" icon="bolt" href="/get-started/quickstart">
    Trial, billing connection, and first report end to end
  </Card>

  <Card title="Billing data" icon="database" href="/setup/billing">
    Providers, ingestion model, and read-only access
  </Card>

  <Card title="AI Assistant (MCP)" icon="sparkles" href="/features/mcp">
    Connect Claude or Cursor to Costory and investigate costs from chat
  </Card>

  <Card title="Cost Reports" icon="paper-plane" href="/features/slack-reports">
    Scheduled cost updates per team channel
  </Card>
</CardGroup>

### When you need more

<CardGroup>
  <Card title="Explorer" icon="chart-bar" href="/features/cost-explorer">
    Multi-cloud exploration, drill-downs, and event context
  </Card>

  <Card title="Digest" icon="list-check" href="/features/digest">
    Monthly tree, ranked changes, and draft summaries you refine before sharing
  </Card>

  <Card title="Dashboards" icon="chart-pie" href="/features/dashboards">
    Turn saved views into shared cost dashboards
  </Card>

  <Card title="Dimensions" icon="tag" href="/features/tagging/dimensions">
    Merge labels, allocate untagged spend, and split shared costs
  </Card>
</CardGroup>


# Billing Data
Source: https://docs.costory.io/setup/billing

Set up cloud billing data sources in Costory via Terraform or manual configuration. Supports AWS CUR 2.0, GCP BigQuery, Azure Cost Management, Snowflake, Scaleway, Cloudflare, and SaaS providers.

Connect your cloud and SaaS billing data so Costory can ingest and normalize it into [Explorer](/features/cost-explorer). You get one schema across providers, with no pipelines to build or maintain.

Once a datasource is added, Costory ingests automatically and maps everything to [Standard Columns](/docs/standard-columns), so you can group and filter costs by service, account, region, resource, and tags across all providers in a single view. Once data is flowing, you can also ask the [Costory MCP](/features/mcp) questions like "what drove the AWS increase last week" directly from your assistant.

<Frame>
  <img alt="Costory Explorer showing multi-cloud cost breakdown by service with period comparison" />
</Frame>

## Supported providers

Click a provider to jump to the setup steps.

<CardGroup>
  <Card title="AWS" href="/setup/billing/aws">
    CUR 2.0 exports via Terraform or manual setup. **\~5 min.**
  </Card>

  <Card title="GCP" href="/setup/billing/gcp">
    BigQuery billing export with detailed usage costs. **\<5 min.**
  </Card>

  <Card title="Azure" href="/setup/billing/azure">
    Azure Cost Management exports with SAS access. **\~5 min.**
  </Card>

  <Card title="Custom Billing Format (FOCUS)" href="/setup/billing/focus">
    Import FOCUS tables from BigQuery. **\<5 min.**
  </Card>

  <Card title="Confluent" href="/setup/billing/confluent">
    Connect Confluent Cloud invoice data. **\<5 min.**
  </Card>

  <Card title="Aiven" href="/setup/billing/aiven">
    Sync Aiven billing via service account. **\<5 min.**
  </Card>

  <Card title="Cursor" href="/setup/billing/cursor">
    Admin API key for usage charges. **\<5 min.**
  </Card>

  <Card title="Anthropic" href="/setup/billing/anthropic">
    Claude Console Admin API or claude.ai Enterprise Analytics. **\<5 min.**
  </Card>

  <Card title="OpenAI" href="/setup/billing/openai">
    Admin API key for Platform organization costs. **\<5 min.**
  </Card>

  <Card title="GCP CUD Metadata" href="/setup/billing/gcp-cud-metadata">
    Commitments metadata from BigQuery exports. **\<5 min.**
  </Card>

  <Card title="Datadog (billing)" href="/setup/billing/datadog">
    Pull Datadog usage and billing estimates. **\<5 min.**
  </Card>

  <Card title="Elastic Cloud" href="/setup/billing/elastic-cloud">
    Organization API key and Organization ID for Elastic Cloud billing. **\<5 min.**
  </Card>

  <Card title="Snowflake" href="/setup/billing/snowflake">
    Snowflake integration (key-pair auth), then billing datasource. **\<5 min.**
  </Card>

  <Card title="ClickHouse Cloud" href="/setup/billing/clickhouse">
    ClickHouse Cloud API key for compute, storage, and transfer. **\<5 min.**
  </Card>

  <Card title="Scaleway" href="/setup/billing/scaleway">
    IAM secret key and Organization ID for Scaleway consumption. **\<5 min.**
  </Card>

  <Card title="Cloudflare" href="/setup/billing/cloudflare">
    API token and Account ID for Cloudflare PayGo usage. **\<5 min.**
  </Card>
</CardGroup>

<Tip>
  **Coming soon:** MongoDB, Databricks, and more. [Contact us](mailto:contact@costory.io) if your provider is missing.&#x20;
</Tip>

## Before you start

* A Costory account.
* Admin billing access to the providers you want to connect (AWS Billing console, GCP Billing Admin, Azure Cost Management). See [Your permissions](#your-permissions) below.
* Read-only access only. Costory never writes to your cloud accounts or modifies your infrastructure. See [Security](/docs/security).
* Connect as many AWS accounts, GCP projects, Azure subscriptions, and SaaS providers as you need within one organization.

Every provider can be connected from the Costory UI; Terraform examples are provided for infrastructure-as-code workflows. If you use Terraform, generate a Costory API token under your org name (top-right) > **API Tokens**. Full reference: [Costory Terraform Provider](https://registry.terraform.io/providers/costory-io/costory/latest/docs).

Already export CUR 2.0 (AWS), BigQuery billing (GCP), or Cost Management data (Azure) for another tool? Reuse it. Grant Costory read access to the existing bucket, dataset, or container instead of creating a second export.

<Tip>
  **Time to first data:** SaaS providers (Cursor, Anthropic, OpenAI, Datadog, Elastic Cloud, Snowflake, Scaleway, Cloudflare, etc.) sync in about **10 minutes**. AWS takes up to **12 hours** for the first CUR export. Costory notifies you by email when data arrives. See [Data Refresh](/docs/data-refresh) for ongoing cadence details.
</Tip>

### Your permissions

To perform the setup, **you** need the following permissions on your cloud account (separate from the read-only access Costory uses afterwards):

| Provider  | Permissions you need                                                                |
| --------- | ----------------------------------------------------------------------------------- |
| **AWS**   | `iam:CreateRole`, `s3:CreateBucket`, Billing console access (to create CUR exports) |
| **GCP**   | BigQuery Admin on the billing dataset, Billing Admin                                |
| **Azure** | Cost Management Contributor, Storage Account Contributor                            |

***

## Historical data backfill

Each provider has different backfill capabilities. Costory ingests whatever history is available in the export:

| Provider           | Backfill depth               | How                                                                                                                                                                            |
| ------------------ | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **AWS**            | Up to **12 months**          | Automatic via `aws:createdBy` tag backfill. For longer periods, open an AWS Support request.                                                                                   |
| **GCP**            | **Current + previous month** | GCP only backfills 2 months by default.                                                                                                                                        |
| **Azure**          | Up to **13 months**          | Use **Export selected dates** in the portal (1-month chunks) or the Terraform `run_backfill` variable.                                                                         |
| **SaaS providers** | Up to **12 months**          | Automatic on first sync (depends on provider data retention).                                                                                                                  |
| **Elastic Cloud**  | **\~6 months** on first sync | [Product-line costs](/setup/billing/elastic-cloud#data-in-costory) per project from the [Elastic Cloud Billing API](/setup/billing/elastic-cloud); incremental sync afterward. |

***

## What happens after setup

Costory normalizes your billing into [Standard Columns](/docs/standard-columns) and prepares [Dimensions](/features/tagging/dimensions) to detect, merge, and clean up your cost allocation tags across providers. Costs are ready in [Explorer](/features/cost-explorer) within minutes (up to 12 hours for the first AWS export).

From there, follow the [Quickstart guide](https://docs.costory.io/get-started/quickstart) to build your first dashboard and set up alerts.

## Next steps

<CardGroup>
  <Card title="Connect external metrics" icon="chart-line" href="/setup/usage-metrics">
    Overlay usage data on your costs for unit economics and root-cause analysis.
  </Card>

  <Card title="Connect Events" icon="calendar" href="/setup/events">
    Link deploys, incidents, and other engineering events for full context.
  </Card>
</CardGroup>

## FAQ

<AccordionGroup>
  <Accordion title="What permissions does Costory need?">
    Costory requires **read-only** access. Here is the minimal permission set per provider:

    | Provider                  | Permissions                                                                                                                                                                |
    | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | **AWS**                   | `s3:ListBucket`, `s3:GetObject` on the CUR export bucket (via federated IAM role)                                                                                          |
    | **GCP**                   | `roles/bigquery.dataViewer`, `roles/bigquery.metadataViewer` on the billing dataset                                                                                        |
    | **Azure**                 | `Read` + `List` on the storage container (via SAS token)                                                                                                                   |
    | **Datadog**               | `usage_read`, `billing_read`, `ci_visibility_read` (optional), `timeseries_query` (optional)                                                                               |
    | **Elastic Cloud**         | Elastic Cloud Organization API key with access to the Billing API (see [Elastic Cloud setup](/setup/billing/elastic-cloud))                                                |
    | **Confluent**             | Billing read access on the API key                                                                                                                                         |
    | **Aiven**                 | `organization:billing:read` on the application user                                                                                                                        |
    | **Cursor**                | Admin API key (organization-scoped, not billing-specific)                                                                                                                  |
    | **Anthropic Claude Code** | Admin API key (`sk-ant-admin01-…`) with usage and cost access                                                                                                              |
    | **Anthropic Claude AI**   | Analytics API key (`sk-ant-api01-…`, scope `read:analytics`). Primary owner on claude.ai                                                                                   |
    | **OpenAI**                | Read-only Admin API key (`sk-admin-...`) with **Usage** (`api.usage.read`). **API keys + Projects** (`api.management.read`) recommended so names appear instead of raw ids |
    | **Scaleway**              | IAM **BillingReadOnly** at Organization scope (secret key + Organization ID)                                                                                               |
    | **Cloudflare**            | API token with **Account / Billing / Read**, plus Account ID (PayGo accounts only)                                                                                         |

    Costory never writes to your cloud accounts. See [Security](/docs/security) for details.
  </Accordion>

  <Accordion title="Can I connect at the organization level instead of per-account?">
    * **AWS**: Yes. Connect a single CUR export from your **management (payer) account** to cover all member accounts in the organization.
    * **GCP**: Yes. The billing export covers **all projects** under the billing account automatically.
    * **Azure**: Exports can be scoped at the Management Group or Billing Account level, but this is often restricted by customer agreements. Per-subscription exports are the most common setup.
  </Accordion>

  <Accordion title="Where does Costory store my data?">
    Costory stores ingested billing data in **GCP EU** by default. If you need US residency, [contact us](mailto:contact@costory.io) to update your configuration. For full details on compliance and certifications, see [Security](/docs/security).
  </Accordion>

  <Accordion title="How do I rotate or update credentials?">
    * **AWS**: No rotation needed. Costory uses a federated IAM role (web identity), so there are no long-lived credentials to manage.
    * **GCP**: No rotation needed. Access is granted via a GCP service account.
    * **Azure**: You can update the SAS token in-place from the Costory UI or via Terraform. The default Terraform config sets a 900-day expiry, so no action is needed for nearly 3 years.
    * **SaaS providers** (Datadog, Confluent, Aiven, Cursor, Anthropic, OpenAI, Elastic Cloud, Scaleway, Cloudflare): Rotate the key from **Integrations** when the provider supports it, or create a new datasource with the new API key and delete the old one. No data gap or re-ingestion occurs.
  </Accordion>

  <Accordion title="Can I delete a datasource? What happens to historical data?">
    Yes, you can delete a datasource from the Costory UI or via `terraform destroy`. **All ingested data for that datasource is permanently deleted.** If you need to restore it, [contact us](mailto:contact@costory.io).
  </Accordion>

  <Accordion title="How do I fully remove Costory from my cloud accounts?">
    Delete the datasource in Costory first, then clean up the cloud-side resources:

    * **AWS**: Delete the S3 bucket, IAM role, and CUR export, or revert the CloudFormation stack if you used that path.
    * **GCP**: Revoke the BigQuery dataset access granted to the Costory service account.
    * **Azure**: Delete the storage account, Cost Management exports, and resource group.

    If you used **Terraform**, `terraform destroy` handles all cloud-side and Costory-side cleanup automatically.
  </Accordion>

  <Accordion title="Can I reuse an existing billing export?">
    Yes. If you already have a billing export for another tool, you do not need a second one:

    * **AWS**: Reuse your existing CUR 2.0 export (Parquet format). Skip the bucket/export creation and only create the federated IAM role so Costory can read the data.
    * **GCP**: There is only one BigQuery billing export table per billing account, so Costory always uses the same table as any other tool.
    * **Azure**: Reuse your existing Cost Management export (Parquet format). Skip the export creation and only generate a SAS token for Costory.
  </Accordion>

  <Accordion title="Does Costory require IP allowlisting or special network rules?">
    No. Costory accesses your data over the **public internet** using the credentials you provide (IAM role, SAS token, or API key). No IP allowlisting, firewall rules, or private connectivity setup is needed on your side.
  </Accordion>

  <Accordion title="What cloud costs does the setup create?">
    The cloud-side costs are **negligible**. You only pay for storage (and minor egress) on the export bucket or dataset:

    * **AWS**: S3 storage for CUR exports. Use **overwrite mode** (enabled by default) to keep storage flat.
    * **GCP**: BigQuery storage for the billing export table.
    * **Azure**: Blob storage for the export container.

    Most billing exports we see across customers are between **500 MB and 2 GB per month**.
  </Accordion>

  <Accordion title="How do I monitor ingestion health?">
    Open [Integrations](https://app.costory.io/integration). Each billing datasource lists the period of billing data Costory has received, for example **from Mar. 1st 2026 to Jul. 24th 2026**.

    * The **from** date is the earliest day Costory has for that source.
    * The **to** date is the latest day Costory has for that source.
    * If the **to** date is current (or matches the expected delay for that provider), ingestion is healthy.

    Costory does not send proactive alerts for ingestion failures today (planned for a future release). For sync frequency and expected freshness per provider, see [Data Refresh Schedule](/docs/data-refresh).
  </Accordion>

  <Accordion title="What if my first AWS CUR export doesn't arrive?">
    The first CUR export can take up to **12 hours**. Costory sends you an email when data is received. If nothing arrives after 12 hours, contact AWS Support to force-trigger the export. This is rare but can happen.

    A common pitfall is **forgetting to backfill historical data**: AWS only exports going forward. Use the `aws:createdBy` tag backfill (up to 12 months) or open an AWS Support request for longer periods.
  </Accordion>

  <Accordion title="What if my connection fails?">
    Costory **validates the connection** when you add a datasource, both via the UI and Terraform. If credentials or permissions are misconfigured (e.g., wrong IAM role trust, invalid SAS token), you'll receive an immediate error message before any sync is attempted.
  </Accordion>

  <Accordion title="Still having trouble?">
    If your question isn't answered here, [contact us](mailto:billy@costory.io). We typically respond within a few hours.
  </Accordion>
</AccordionGroup>

***


# Aiven Billing Setup
Source: https://docs.costory.io/setup/billing/aiven

Connect Aiven billing data to Costory via the Aiven Billing API.

<Tabs>
  <Tab title="Terraform">
    Not supported.
  </Tab>

  <Tab title="Manual setup">
    Open Costory and go to **Billing > Import new billing datasource > Aiven**. The stepper guides you through each field.

    1. In the Aiven console, create a dedicated `costory` application user and grant it **organization:billing:read** permission.
    2. Generate an API token for the `costory` application user.
    3. Enter the **Organization ID** and **API Token** in the Costory stepper.

    Costory fetches invoice data via the Aiven Billing API. On first sync, Costory backfills up to **12 months** of historical data (depending on your Aiven account). New data appears the next day.
  </Tab>
</Tabs>

**What Costory includes**

* **Invoice-level billing data** from all Aiven services in your organization.
* **Per-service cost breakdown** (group by **Service name**).

**What Costory does not include**

* **Credits or promotional discounts** outside invoice line items.
* **Aiven support or marketplace fees** that are billed separately.


# Anthropic Billing Setup
Source: https://docs.costory.io/setup/billing/anthropic

Connect Anthropic Claude Console API usage and claude.ai Enterprise costs to Costory. Choose the right connector and key type.

Anthropic reports cost through two APIs. They use different keys and are not interchangeable. Pick the connector that matches where you pay, then paste the matching key.

If you call Claude through Amazon Bedrock instead of Anthropic's own APIs, that spend lands via the [AWS connector](/setup/billing/aws). For team-level allocation after data is in, see [LLM cost allocation](/use-cases/llm-ai-cost).

## Which connector to use

| Your organization                                  | Connector in Costory      | Key                                                          |
| -------------------------------------------------- | ------------------------- | ------------------------------------------------------------ |
| Claude Console (Claude Platform)                   | **Anthropic Claude Code** | Admin API key (`sk-ant-admin01-…`)                           |
| Claude Enterprise ([claude.ai](https://claude.ai)) | **Anthropic Claude AI**   | Analytics API key (`sk-ant-api01-…`, scope `read:analytics`) |

Claude Enterprise parent organizations do not appear in Claude Console and have no Admin API keys. A Console Admin key will not work on **Anthropic Claude AI**. An Analytics API key will not work on **Anthropic Claude Code**.

<Info>
  Connect both if you pay for Console API usage and a claude.ai Enterprise org. Each connector is a separate billing datasource.
</Info>

## Connect Anthropic Claude Code

Use this connector for Claude Console (Claude Platform) API usage and subscription usage exposed by the [Usage and Cost Admin API](https://platform.claude.com/docs/en/build-with-claude/usage-cost-api).

<Tabs>
  <Tab title="Manual setup">
    <Steps>
      <Step title="Create an Admin API key">
        In [Claude Console > Settings > Admin keys](https://platform.claude.com/settings/admin-keys), create an **Admin API key** with usage and cost access. You must be an organization **admin**. Copy it immediately (`sk-ant-admin01-…`). A standard Claude API key will not work.
      </Step>

      <Step title="Connect in Costory">
        Go to [Integrations](https://app.costory.io/integration), click **+ Add integration**, then choose **Anthropic Claude Code** under **Billing**.
      </Step>

      <Step title="Enter connection details">
        Fill **Connection name** (default **Anthropic**) and **Admin API key**. **Start date** is optional. Leave it empty to use Costory's default lookback.
      </Step>

      <Step title="Validate, then save">
        Click **Validate**. **Save** stays disabled until the Admin API key can read organization usage and cost. If this is the only billing source and it is demo data, Costory asks you to confirm before replacing it.
      </Step>
    </Steps>

    On first sync, Costory backfills up to **12 months** of historical usage data. New data then follows the usual [data refresh](/docs/data-refresh) cadence. SaaS sources typically appear in about **10 minutes**.
  </Tab>

  <Tab title="Terraform">
    ```hcl theme={null}
    terraform {
      required_providers {
        costory = {
          source  = "costory-io/costory"
          version = ">= 0.1.0"
        }
      }
    }

    variable "costory_api_token" {
      type        = string
      description = "Costory API token."
      sensitive   = true
    }

    variable "anthropic_admin_api_key" {
      type        = string
      description = "Anthropic admin API key used to fetch billing data."
      sensitive   = true
    }

    provider "costory" {
      token = var.costory_api_token
    }

    resource "costory_billing_datasource_anthropic" "main" {
      name          = "Anthropic Billing"
      admin_api_key = var.anthropic_admin_api_key
    }
    ```
  </Tab>
</Tabs>

### What Costory includes

* **API usage** and **subscription usage** from Anthropic billing exports.
* **Included plan usage** labeled as `Included<subscription_type>` in **Charge description** (for Business/Enterprise plans).
* **Per-model breakdown** (group by **Service name** = model).
* **Per-actor attribution** using user email or API key name.

**What Costory does not include**

* **Taxes, credits, and adjustments** outside usage line items.
* **Non-usage fees** that do not appear in the Anthropic billing export.
* **claude.ai Enterprise** seat or usage-credit costs. Use [Anthropic Claude AI](#connect-anthropic-claude-ai) for those.

**How to analyze Anthropic Claude Code costs**

* **Included vs API usage:** filter by **Charge description**:
  * `Included<subscription_type>` for subscription usage.
  * `API` for pay-as-you-go usage.
* **Per-user email spend:** group by **Resource name** or **Sub account id** (mapped to the actor email or API key name).
* **Per-model costs:** group by **Service name** (model) and break down by **SKU** (`input` vs `output` tokens).

<Note>
  Anthropic Console costs are attributed to **input tokens**. Output token rows are included for usage analysis but have \$0 cost.
</Note>

## Connect Anthropic Claude AI

Use this connector for Claude Enterprise costs on [claude.ai](https://claude.ai). Costory reads per-user cost from the [Get Per-User Cost](https://platform.claude.com/docs/en/api/http/admin/analytics/cost/list_by_user) endpoint. See Anthropic's [Analytics API](https://platform.claude.com/docs/en/manage-claude/analytics-api) for how to enable access.

<Warning>
  You must sign in as the organization **primary owner**. Only the primary owner can enable public API access and create the Analytics API key.
</Warning>

<Steps>
  <Step title="Enable public API access">
    Sign in to [claude.ai](https://claude.ai) as the **primary owner**. Open [claude.ai > Organization settings > API](https://platform.claude.com/docs/en/manage-claude/analytics-api) and enable public API access.
  </Step>

  <Step title="Create an Analytics API key">
    Create an Analytics API key with scope **read:analytics**. Copy it immediately (`sk-ant-api01-…`). A Console Admin key (`sk-ant-admin01-…`) will not work.
  </Step>

  <Step title="Connect in Costory">
    Go to [Integrations](https://app.costory.io/integration), click **+ Add integration**, then choose **Anthropic Claude AI** under **Billing**.
  </Step>

  <Step title="Enter connection details">
    Fill **Connection name** (default **Anthropic Claude AI**), **Account name**, and **Analytics API key**. **Start date** is optional. Leave it empty to use Costory's default lookback.
  </Step>

  <Step title="Validate, then save">
    Click **Validate**. **Save** stays disabled until the Analytics API key can read Claude Enterprise per-user cost. If this is the only billing source and it is demo data, Costory asks you to confirm before replacing it.
  </Step>
</Steps>

On first sync, Costory backfills up to **12 months** of historical usage data, depending on what Anthropic retains. New data then follows the usual [data refresh](/docs/data-refresh) cadence.

### Field reference

| Field                 | Required | Description                                                                                |
| --------------------- | -------- | ------------------------------------------------------------------------------------------ |
| **Connection name**   | Yes      | Label in **Integrations**.                                                                 |
| **Account name**      | Yes      | Label for this Claude Enterprise org. Stored as **Sub account id**. Not sent to Anthropic. |
| **Analytics API key** | Yes      | Primary-owner key with `read:analytics`. Stored in Costory's secret manager.               |
| **Start date**        | No       | Optional start of the first sync. Leave empty for the default lookback.                    |

### What Costory includes

* **Per-user cost** from the Claude Enterprise Analytics API.
* Your **Account name** as **Sub account id**, so you can tell multiple Enterprise orgs apart.

**What Costory does not include**

* **Claude Console / API** usage. Use [Anthropic Claude Code](#connect-anthropic-claude-code) for that.
* **Unattributed org-wide API-key or automation traffic** (the org-wide cost report is out of scope).
* **Seat SKU** on seat-based Enterprise plans. Those plans only show usage credits.

<Note>
  Seat-based Enterprise plans only show usage credits, not the seat SKU. Cost and usage endpoints apply to usage-based Enterprise plans. For seat-based plans they reflect usage credits only.
</Note>

<Info>
  Rotate the Analytics API key from **Integrations** when you need a new credential. **Account name** stays the same.
</Info>

## Troubleshooting

| Issue                                 | What to check                                                                                                                                                    |
| ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Admin key rejected on Claude AI       | You pasted a Console Admin key (`sk-ant-admin01-…`). Use **Anthropic Claude Code** for that key, or create an Analytics key (`sk-ant-api01-…`) as primary owner. |
| Analytics key rejected on Claude Code | You pasted an Analytics API key. Use **Anthropic Claude AI** for claude.ai Enterprise costs.                                                                     |
| Access denied (403)                   | Confirm you are the **primary owner**, public API access is enabled, and the key has `read:analytics`.                                                           |
| No cost data on a seat-based plan     | Expected. Seat-based plans expose usage credits only, not the seat SKU.                                                                                          |
| Failed to authenticate                | Recreate the key in the matching console: Admin keys in Claude Console, Analytics keys in claude.ai Organization settings > API.                                 |

## Related

* [Billing Data](/setup/billing)
* [LLM cost allocation](/use-cases/llm-ai-cost)
* [OpenAI Billing Setup](/setup/billing/openai)
* [Cursor Billing Setup](/setup/billing/cursor)
* [Data Refresh](/docs/data-refresh)


# AWS Billing Setup
Source: https://docs.costory.io/setup/billing/aws

Connect AWS CUR 2.0 billing data to Costory via CloudFormation, manual setup, or Terraform.

<Tabs>
  <Tab title="Manual setup">
    In Costory, go to **Billing > Import new billing datasource > AWS** and follow the stepper. First prepare your AWS account using CloudFormation or a manual setup. Both produce the same result: an S3 bucket with <Tooltip href="/docs/glossary#cur">CUR 2.0</Tooltip> data and an IAM role Costory can assume.

    **Option A: CloudFormation (recommended)**

    1. Open the [CloudFormation template](https://us-east-1.console.aws.amazon.com/cloudformation/home?region=us-east-1#/stacks/create/review?templateURL=https://costory-public-templates.s3.us-east-1.amazonaws.com/create_cur2_and_assign_iam_rights_v2.yaml) in **us-east-1**.
    2. Deploy the stack and note the **Bucket Name**, **Role ARN**, and **Prefix** from the stack outputs.

    **Option B: Manual**

    1. Create a CUR 2.0 data export in the AWS Billing console (Parquet format, overwrite enabled). Use hourly granularity if you run EKS or ECS. Enable all checkboxes under Additional Content (Include ID resources, Include Split cost allocation data, etc...).
    2. Create an S3 read-only IAM policy scoped to the export bucket.
    3. Create a web identity IAM role trusted by Costory's GCP service account.

    **Connect in Costory**

    1. Go to **Billing > Import new billing datasource > AWS**.
    2. Enter the **S3 bucket name**, **Role ARN**, and **Prefix**.
    3. If you run EKS or ECS, enable **<Tooltip href="/docs/glossary#split-cost-allocation">Split cost allocation data</Tooltip>** and activate the relevant cost allocation tags (`aws:eks:*`, `aws:ecs:*`). This gives you pod-level (EKS) and job-level (ECS) cost granularity. See [Kubernetes cost visibility](/use-cases/k8s_waste/visibility) for details.

    <Tip>
      **Cost allocation tags:** Activate as many cost allocation tags as you can in the AWS Billing console. Costory [Dimensions](/features/tagging/dimensions) automatically detect and merge meaningful tags so you can filter by team, environment, project, etc.
    </Tip>

    <Note>
      The first AWS export can take up to **12 hours**. Costory sends you an email when data is received. Backfill covers up to **12 months** via `aws:createdBy` tag backfill. For longer periods, open an AWS Support request.
    </Note>

    <Frame>
      <img alt="Costory datasource successfully connected" />
    </Frame>
  </Tab>

  <Tab title="Terraform">
    <Accordion title="Full Terraform configuration">
      ```hcl theme={null}
      terraform {
        required_providers {
          aws = {
            source  = "hashicorp/aws"
            version = ">= 5.0"
          }
          costory = {
            source  = "costory-io/costory"
            version = ">= 0.1.0"
          }
        }
      }
      variable "s3_name" {
        type        = string
        description = "Base name for the CUR bucket."
        default     = "billing-data-exports"
      }

      variable "s3_prefix" {
        type        = string
        description = "The S3 prefix for the CUR exports."
        default     = "costory-cur"
      }

      variable "aws_region" {
        type        = string
        description = "AWS region used by this Terraform stack."
        default     = "us-east-1"
      }

      variable "costory_api_token" {
        type        = string
        description = "Costory API token."
        sensitive   = true
      }

      provider "costory" {
        token = var.costory_api_token
      }

      provider "aws" {
        region = var.aws_region
      }

      data "aws_caller_identity" "current" {}
      data "aws_partition" "current" {}
      data "costory_service_account" "current" {}


      locals {
        account_id = data.aws_caller_identity.current.account_id

        cur_bucket_name = "${var.s3_name}-${local.account_id}"
        cur_export_name = "${var.s3_name}-costory-data-exports"
        # Issue with AWS provider see https://github.com/hashicorp/terraform-provider-aws/issues/43978
        cur_definition_source_arn = "arn:${data.aws_partition.current.partition}:cur:us-east-1:${local.account_id}:definition/*"
        bcm_export_source_arn     = "arn:${data.aws_partition.current.partition}:bcm-data-exports:us-east-1:${local.account_id}:export/*"

        cur_table_configurations = {
          COST_AND_USAGE_REPORT = {
            INCLUDE_RESOURCES                     = "TRUE"
            INCLUDE_SPLIT_COST_ALLOCATION_DATA    = "TRUE"
            TIME_GRANULARITY                      = "HOURLY"
            INCLUDE_MANUAL_DISCOUNT_COMPATIBILITY = "FALSE"
            INCLUDE_CAPACITY_RESERVATION_DATA     = "TRUE"
            BILLING_VIEW_ARN                      = "arn:${data.aws_partition.current.partition}:billing::${data.aws_caller_identity.current.account_id}:billingview/primary"
            INCLUDE_IAM_PRINCIPAL_DATA            = "TRUE"
          }
        }
        // SQL Query to get all columns
        cur_query_statement = <<-EOT
      SELECT bill_bill_type, bill_billing_entity, bill_billing_period_end_date, bill_billing_period_start_date, bill_invoice_id, bill_invoicing_entity, bill_payer_account_id, bill_payer_account_name, capacity_reservation_capacity_reservation_arn, capacity_reservation_capacity_reservation_status, capacity_reservation_capacity_reservation_type, cost_category, discount, discount_bundled_discount, discount_total_discount, identity_line_item_id, identity_time_interval, line_item_availability_zone, line_item_blended_cost, line_item_blended_rate, line_item_currency_code, line_item_iam_principal, line_item_legal_entity, line_item_line_item_description, line_item_line_item_type, line_item_net_unblended_cost, line_item_net_unblended_rate, line_item_normalization_factor, line_item_normalized_usage_amount, line_item_operation, line_item_product_code, line_item_resource_id, line_item_tax_type, line_item_unblended_cost, line_item_unblended_rate, line_item_usage_account_id, line_item_usage_account_name, line_item_usage_amount, line_item_usage_end_date, line_item_usage_start_date, line_item_usage_type, line_item_user_identifier, pricing_currency, pricing_lease_contract_length, pricing_offering_class, pricing_public_on_demand_cost, pricing_public_on_demand_rate, pricing_purchase_option, pricing_rate_code, pricing_rate_id, pricing_term, pricing_unit, product, product_comment, product_fee_code, product_fee_description, product_from_location, product_from_location_type, product_from_region_code, product_instance_family, product_instance_type, product_instancesku, product_location, product_location_type, product_operation, product_pricing_unit, product_product_family, product_region_code, product_servicecode, product_sku, product_to_location, product_to_location_type, product_to_region_code, product_usagetype, reservation_amortized_upfront_cost_for_usage, reservation_amortized_upfront_fee_for_billing_period, reservation_availability_zone, reservation_effective_cost, reservation_end_time, reservation_modification_status, reservation_net_amortized_upfront_cost_for_usage, reservation_net_amortized_upfront_fee_for_billing_period, reservation_net_effective_cost, reservation_net_recurring_fee_for_usage, reservation_net_unused_amortized_upfront_fee_for_billing_period, reservation_net_unused_recurring_fee, reservation_net_upfront_value, reservation_normalized_units_per_reservation, reservation_number_of_reservations, reservation_recurring_fee_for_usage, reservation_reservation_a_r_n, reservation_start_time, reservation_subscription_id, reservation_total_reserved_normalized_units, reservation_total_reserved_units, reservation_units_per_reservation, reservation_unused_amortized_upfront_fee_for_billing_period, reservation_unused_normalized_unit_quantity, reservation_unused_quantity, reservation_unused_recurring_fee, reservation_upfront_value, resource_tags, savings_plan_amortized_upfront_commitment_for_billing_period, savings_plan_end_time, savings_plan_instance_type_family, savings_plan_net_amortized_upfront_commitment_for_billing_period, savings_plan_net_recurring_commitment_for_billing_period, savings_plan_net_savings_plan_effective_cost, savings_plan_offering_type, savings_plan_payment_option, savings_plan_purchase_term, savings_plan_recurring_commitment_for_billing_period, savings_plan_region, savings_plan_savings_plan_a_r_n, savings_plan_savings_plan_effective_cost, savings_plan_savings_plan_rate, savings_plan_start_time, savings_plan_total_commitment_to_date, savings_plan_used_commitment, split_line_item_actual_usage, split_line_item_net_split_cost, split_line_item_net_unused_cost, split_line_item_parent_resource_id, split_line_item_public_on_demand_split_cost, split_line_item_public_on_demand_unused_cost, split_line_item_reserved_usage, split_line_item_split_cost, split_line_item_split_usage, split_line_item_split_usage_ratio, split_line_item_unused_cost, tags FROM COST_AND_USAGE_REPORT
      EOT
      }
      # Creates AWS Billing Data Export:

      resource "aws_s3_bucket" "s3_client_bucket" {
        bucket = local.cur_bucket_name
      }

      resource "aws_s3_bucket_public_access_block" "s3_client_bucket" {
        bucket = aws_s3_bucket.s3_client_bucket.id

        ignore_public_acls      = true
        restrict_public_buckets = true
      }

      data "aws_iam_policy_document" "s3_client_bucket_access_policy" {
        statement {
          effect = "Allow"
          principals {
            type = "Service"
            identifiers = [
              "billingreports.amazonaws.com",
              "bcm-data-exports.amazonaws.com",
            ]
          }
          actions = [
            "s3:PutObject",
            "s3:GetBucketPolicy",
          ]
          resources = [
            aws_s3_bucket.s3_client_bucket.arn,
            "${aws_s3_bucket.s3_client_bucket.arn}/*",
          ]
          condition {
            test     = "StringLike"
            variable = "aws:SourceArn"
            values = [
              local.cur_definition_source_arn,
              local.bcm_export_source_arn,
            ]
          }
          condition {
            test     = "StringLike"
            variable = "aws:SourceAccount"
            values   = [local.account_id]
          }
        }
      }

      resource "aws_s3_bucket_policy" "s3_client_bucket_access_policy" {
        bucket = aws_s3_bucket.s3_client_bucket.id
        policy = data.aws_iam_policy_document.s3_client_bucket_access_policy.json
      }

      resource "aws_bcmdataexports_export" "cur_report_definition" {
        depends_on = [aws_s3_bucket_policy.s3_client_bucket_access_policy]
        export {
          name = local.cur_export_name
          data_query {
            query_statement      = local.cur_query_statement
            table_configurations = local.cur_table_configurations
          }
          destination_configurations {
            s3_destination {
              s3_bucket = aws_s3_bucket.s3_client_bucket.bucket
              s3_region = var.aws_region
              s3_prefix = var.s3_prefix

              s3_output_configurations {
                compression = "PARQUET"
                format      = "PARQUET"
                output_type = "CUSTOM"
                overwrite   = "OVERWRITE_REPORT"
              }
            }
          }
          refresh_cadence {
            frequency = "SYNCHRONOUS"
          }
        }
      }
      # Give Costory permission to read the S3 bucket:

      data "aws_iam_policy_document" "costory_read_s3_policy" {
        statement {
          sid    = "Statement1"
          effect = "Allow"
          actions = [
            "s3:ListBucket",
            "s3:GetObject",
          ]
          resources = [
            aws_s3_bucket.s3_client_bucket.arn,
            "${aws_s3_bucket.s3_client_bucket.arn}/*",
          ]
        }
      }
      resource "aws_iam_policy" "costory_read_s3_policy" {
        name        = "Costory-read-s3-${var.s3_name}"
        description = "Allows Costory to read the CUR S3 bucket."
        policy      = data.aws_iam_policy_document.costory_read_s3_policy.json
      }
      # Costory is hosted on GCP we rely on a federated role on your organization service account to access the AWS billing data export.
      data "aws_iam_policy_document" "costory_federated_role_assume" {
        statement {
          effect = "Allow"
          actions = [
            "sts:AssumeRoleWithWebIdentity",
          ]
          principals {
            type        = "Federated"
            identifiers = ["accounts.google.com"]
          }
          condition {
            test     = "StringEquals"
            variable = "accounts.google.com:sub"
            values   = data.costory_service_account.current.sub_ids
          }
        }
      }
      resource "aws_iam_role" "costory_federated_role" {
        name               = "costory-trust-link-${var.s3_name}"
        assume_role_policy = data.aws_iam_policy_document.costory_federated_role_assume.json
      }
      resource "aws_iam_role_policy_attachment" "costory_read_s3_policy_attachment" {
        role       = aws_iam_role.costory_federated_role.name
        policy_arn = aws_iam_policy.costory_read_s3_policy.arn
      }
      # Create the Costory AWS billing datasource in Costory:
      resource "costory_billing_datasource_aws" "main" {
        name                   = "AWS CUR ${var.s3_name}"
        bucket_name            = aws_s3_bucket.s3_client_bucket.bucket
        role_arn               = aws_iam_role.costory_federated_role.arn
        prefix                 = var.s3_prefix
        eks_split_data_enabled = true
        depends_on             = [aws_bcmdataexports_export.cur_report_definition]
      }
      ```
    </Accordion>
  </Tab>
</Tabs>

<Note>
  If required, you can import an AWS CUR V1 datasource in Costory: follow the same path as manual import of existing CUR V1 datasource. We don't recommend this approach as the data is less detailed than CUR 2.0.
</Note>


# Azure Billing Setup
Source: https://docs.costory.io/setup/billing/azure

Connect Azure Cost Management exports to Costory via Terraform or manual setup.

<Tabs>
  <Tab title="Terraform">
    ```hcl theme={null}
    terraform {
      required_version = ">= 1.5"

      required_providers {
        azurerm = {
          source  = "hashicorp/azurerm"
          version = "~> 4.0"
        }
        azapi = {
          source  = "Azure/azapi"
          version = "~> 2.0"
        }
        random = {
          source  = "hashicorp/random"
          version = "~> 3.0"
        }
        time = {
          source  = "hashicorp/time"
          version = "~> 0.11"
        }
        costory = {
          source  = "costory-io/costory"
          version = "~> 0.2"
        }
      }
    }

    variable "costory_api_token" {
      type        = string
      description = "Costory API token."
      sensitive   = true
    }

    variable "subscription_id" {
      type        = string
      description = "Azure subscription ID."
    }

    variable "location" {
      type        = string
      description = "Azure region for all resources."
      default     = "West Europe"
    }

    variable "resource_group_name" {
      type        = string
      description = "Name of the resource group to create."
      default     = "costory-cost-exports"
    }

    variable "storage_account_name_prefix" {
      type        = string
      description = "Prefix for the storage account name (a random suffix is appended for uniqueness)."
      default     = "costexports"
    }

    variable "sas_token_validity_days" {
      type        = number
      description = "Number of days the SAS token remains valid."
      default     = 900
    }

    variable "backfill_month_count" {
      type        = number
      description = "Number of past months to backfill (0 to skip)."
      default     = 12
    }

    variable "run_backfill" {
      type        = bool
      description = "Set to true to trigger backfill runs. Use: terraform apply -var='run_backfill=true'"
      default     = false
    }

    provider "azurerm" {
      features {}
      subscription_id = var.subscription_id
    }

    provider "costory" {
      token = var.costory_api_token
    }

    resource "azurerm_resource_group" "cost_exports" {
      name     = var.resource_group_name
      location = var.location
    }

    resource "random_string" "storage_suffix" {
      length  = 8
      special = false
      upper   = false
    }

    resource "azurerm_storage_account" "cost_exports" {
      name                     = "${var.storage_account_name_prefix}${random_string.storage_suffix.result}"
      resource_group_name      = azurerm_resource_group.cost_exports.name
      location                 = azurerm_resource_group.cost_exports.location
      account_tier             = "Standard"
      account_replication_type = "LRS"
      min_tls_version          = "TLS1_2"
    }

    resource "azurerm_storage_container" "billing" {
      name               = "billing-exports"
      storage_account_id = azurerm_storage_account.cost_exports.id
    }

    resource "time_static" "export_start" {}

    locals {
      actuals_export_name   = "costory-actuals-${random_string.storage_suffix.result}"
      amortized_export_name = "costory-amortized-${random_string.storage_suffix.result}"
    }

    resource "azapi_resource" "actuals" {
      type      = "Microsoft.CostManagement/exports@2025-03-01"
      name      = local.actuals_export_name
      parent_id = "/subscriptions/${var.subscription_id}"

      body = {
        properties = {
          definition = {
            type      = "ActualCost"
            timeframe = "MonthToDate"
            dataSet = {
              granularity = "Daily"
            }
          }
          schedule = {
            status     = "Active"
            recurrence = "Daily"
            recurrencePeriod = {
              from = time_static.export_start.rfc3339
              to   = "2099-01-01T00:00:00Z"
            }
          }
          format        = "Parquet"
          partitionData = true
          deliveryInfo = {
            destination = {
              container      = azurerm_storage_container.billing.name
              resourceId     = azurerm_storage_account.cost_exports.id
              rootFolderPath = "actuals"
            }
          }
        }
      }
    }

    resource "azapi_resource" "amortized" {
      type      = "Microsoft.CostManagement/exports@2025-03-01"
      name      = local.amortized_export_name
      parent_id = "/subscriptions/${var.subscription_id}"

      body = {
        properties = {
          definition = {
            type      = "AmortizedCost"
            timeframe = "MonthToDate"
            dataSet = {
              granularity = "Daily"
            }
          }
          schedule = {
            status     = "Active"
            recurrence = "Daily"
            recurrencePeriod = {
              from = time_static.export_start.rfc3339
              to   = "2099-01-01T00:00:00Z"
            }
          }
          format        = "Parquet"
          partitionData = true
          deliveryInfo = {
            destination = {
              container      = azurerm_storage_container.billing.name
              resourceId     = azurerm_storage_account.cost_exports.id
              rootFolderPath = "amortized"
            }
          }
        }
      }
    }

    locals {
      absolute_month = tonumber(formatdate("YYYY", plantimestamp())) * 12 + tonumber(formatdate("M", plantimestamp())) - 1

      backfill_months = [
        for i in range(1, var.backfill_month_count + 1) : format(
          "%04d-%02d",
          floor((local.absolute_month - i) / 12),
          (local.absolute_month - i) % 12 + 1,
        )
      ]

      backfill_ranges = {
        for m in local.backfill_months : m => {
          from = "${m}-01T00:00:00Z"
          to = "${formatdate(
            "YYYY-MM-DD",
            timeadd(
              format(
                "%04d-%02d-01T00:00:00Z",
                tonumber(split("-", m)[1]) == 12 ? tonumber(split("-", m)[0]) + 1 : tonumber(split("-", m)[0]),
                tonumber(split("-", m)[1]) == 12 ? 1 : tonumber(split("-", m)[1]) + 1,
              ),
              "-24h",
            ),
          )}T00:00:00Z"
        }
      }
    }

    resource "azapi_resource_action" "backfill_actuals" {
      for_each = var.run_backfill ? local.backfill_ranges : {}

      type        = "Microsoft.CostManagement/exports@2025-03-01"
      resource_id = azapi_resource.actuals.id
      action      = "run"
      method      = "POST"
      when        = "apply"

      body = {
        timePeriod = {
          from = each.value.from
          to   = each.value.to
        }
      }
    }

    resource "azapi_resource_action" "backfill_amortized" {
      for_each = var.run_backfill ? local.backfill_ranges : {}

      type        = "Microsoft.CostManagement/exports@2025-03-01"
      resource_id = azapi_resource.amortized.id
      action      = "run"
      method      = "POST"
      when        = "apply"

      body = {
        timePeriod = {
          from = each.value.from
          to   = each.value.to
        }
      }
    }

    resource "time_static" "sas_start" {}

    data "azurerm_storage_account_sas" "billing" {
      connection_string = azurerm_storage_account.cost_exports.primary_connection_string
      https_only        = true
      signed_version    = "2022-11-02"

      start  = time_static.sas_start.rfc3339
      expiry = timeadd(time_static.sas_start.rfc3339, "${var.sas_token_validity_days * 24}h")

      resource_types {
        service   = false
        container = true
        object    = true
      }

      services {
        blob  = true
        queue = false
        table = false
        file  = false
      }

      permissions {
        read    = true
        write   = false
        delete  = false
        list    = true
        add     = false
        create  = false
        update  = false
        process = false
        tag     = false
        filter  = false
      }
    }

    locals {
      blob_endpoint_with_sas = "${azurerm_storage_account.cost_exports.primary_blob_endpoint}${azurerm_storage_container.billing.name}${data.azurerm_storage_account_sas.billing.sas}"
    }

    resource "costory_billing_datasource_azure" "main" {
      name                 = "Azure Production"
      sas_url              = local.blob_endpoint_with_sas
      storage_account_name = azurerm_storage_account.cost_exports.name
      container_name       = azurerm_storage_container.billing.name
      actuals_path         = "actuals/${local.actuals_export_name}"
      amortized_path       = "amortized/${local.amortized_export_name}"
    }

    output "storage_account_name" {
      value = azurerm_storage_account.cost_exports.name
    }

    output "storage_container_name" {
      value = azurerm_storage_container.billing.name
    }

    output "sas_token" {
      value     = data.azurerm_storage_account_sas.billing.sas
      sensitive = true
    }

    output "blob_endpoint_with_sas" {
      description = "Full blob endpoint URL with SAS token for accessing billing exports."
      value       = local.blob_endpoint_with_sas
      sensitive   = true
    }

    output "sas_token_expiry" {
      value = timeadd(time_static.sas_start.rfc3339, "${var.sas_token_validity_days * 24}h")
    }
    ```

    **Backfilling historical data**

    Azure exports only produce data going forward. To import past months, the module triggers one-off export runs via `azapi_resource_action`. Two variables control this:

    | Variable               | Default | Description                                 |
    | ---------------------- | ------- | ------------------------------------------- |
    | `backfill_month_count` | `12`    | Number of past months to export.            |
    | `run_backfill`         | `false` | Set to `true` to trigger the backfill runs. |

    Run the backfill as a separate apply:

    ```bash theme={null}
    terraform apply -var='run_backfill=true'
    ```

    This calls the Azure `exports/run` API for both the actuals and amortized exports, one calendar month at a time. Azure writes the Parquet files to the same container and Costory picks them up on the next sync. Set `run_backfill` back to `false` afterward to avoid re-triggering on future applies.
  </Tab>

  <Tab title="Manual setup">
    In Costory, go to **Billing > Import new billing datasource > Azure** and follow the stepper. First prepare your Azure account:

    1. Navigate to **Azure Cost Management > Exports**.
    2. Create two exports using the **Cost and Usage** template: one for **Actual Cost** and one for **<Tooltip href="/docs/glossary#amortized-cost">Amortized Cost</Tooltip>**. Set both to **Daily** recurrence.
    3. Configure a storage account and container as the export destination.
    4. Trigger an immediate export run for both exports.
    5. On the storage account, create an **access policy** with **Read** and **List** permissions. Set the expiry to at least **900 days** (the same default used in the Terraform config). Then generate a **SAS token** from this policy.
    6. In Costory, go to **Billing > Import new billing datasource > Azure**. Paste the full SAS URL (blob endpoint + container + SAS token), then select **Check Available Files**, confirm detected prefixes, and select **Import**.

    <Note>
      To backfill historical data, use **Export selected dates** in the Azure portal in 1-month chunks (up to 13 months).
    </Note>
  </Tab>
</Tabs>


# ClickHouse Billing Setup
Source: https://docs.costory.io/setup/billing/clickhouse

Connect ClickHouse Cloud billing data to Costory to analyze compute, storage, and data transfer costs.

<Tabs>
  <Tab title="Terraform">
    Not supported.
  </Tab>

  <Tab title="Manual setup">
    Open Costory and go to **Billing > Import new billing datasource > ClickHouse**. The stepper guides you through each field.

    1. Generate a **ClickHouse Cloud API Key** and Secret with billing/organization read access.
    2. Provide your **Organization ID**, **API Key**, and **API Secret** in the Costory stepper.

    On first sync, Costory backfills historical usage and service data.
  </Tab>
</Tabs>

**What Costory includes**

Costory ingests your daily usage metrics and translates them directly into standardized FinOps dimensions.

* **Compute & Storage costs:** Direct visibility into `computeCHC`, `storageCHC`, and `backupCHC` charges.
* **Data Transfer metrics:** Breakdown of networking costs including `dataTransferCHC`, `publicDataTransferCHC`, and `interRegion` tier transfers.
* **Service & Resource context:** Breakdowns by `dataWarehouseId`, `serviceId`, environment `state`, and `provider`.
* **Custom Tags:** Any service tags applied in ClickHouse are automatically ingested as Costory labels (prefixed with `clickhouse_`).

**What Costory does not include**

* **ClickHouse Open Source / Self-managed:** Only ClickHouse Cloud is supported.
* **Taxes and support fees:** Non-usage invoice items are not currently mapped from the usage metrics API.

**How to analyze ClickHouse costs**

* **Per-Service or per-Cluster spend:** Group by **Resource name** (Service display name) or **Resource ID** (`entityId`).
* **Spend by Metric:** Group by **SKU** to compare `compute`, `storage`, and `dataTransfer` costs.
* **By Environment:** Group by the `service_state` label or any custom `clickhouse_*` labels you have defined in your infrastructure.

<Note>
  ClickHouse metrics are recorded in ClickHouse Credits (`CHC`) and converted to a standard currency. Costory normalizes these values so they sit alongside your AWS, GCP, and Azure spend.
</Note>


# Cloudflare Billing Setup
Source: https://docs.costory.io/setup/billing/cloudflare

Connect Cloudflare PayGo billing to Costory with an API token and Account ID. Self-serve usage only, not enterprise contract billing.

Workers, R2, and other PayGo products often sit on a separate bill from AWS, GCP, and Azure. Connect Cloudflare with an **API token** and **Account ID** so that spend lands in [Explorer](/features/cost-explorer) with your other [billing datasources](/setup/billing).

This connector imports **PayGo** (self-serve) usage only.

<Warning>
  PayGo and self-serve accounts only. Enterprise contract billing is not on the public usage API. Validation fails with a coverage error if the account is not covered.
</Warning>

<Tabs>
  <Tab title="Manual setup">
    <Steps>
      <Step title="Create an API token">
        In [Cloudflare Dashboard > My Profile > API Tokens](https://developers.cloudflare.com/fundamentals/api/get-started/create-token/), create a token. Permission: **Account / Billing / Read**, scoped to this account. Copy the token immediately. It is shown once. Global API keys and Origin CA keys will not work.
      </Step>

      <Step title="Copy the Account ID">
        Copy the **Account ID** from the dashboard Overview page (right-hand sidebar) or from the URL (`/accounts/<account-id>/...`). It is 32 hex characters.
      </Step>

      <Step title="Connect in Costory">
        Go to [Integrations](https://app.costory.io/integration), click **+ Add integration**, then choose **Cloudflare** under **Billing**. The connect URL is `/integration/new/cloudflare/billing`.&#x20;
      </Step>

      <Step title="Enter connection details">
        Fill **Connection name** (default **Cloudflare**), **API token**, and **Account ID**. **Start date** is optional. Leave it empty to use Costory's default lookback.
      </Step>

      <Step title="Validate, then save">
        Click **Validate**. Costory calls `GET /client/v4/accounts/<account-id>/billing-usage/info` with `Authorization: Bearer`. **Save** stays disabled until the token can read PayGo billing for that account. If this is the only billing source and it is demo data, Costory asks you to confirm before replacing it.
      </Step>
    </Steps>

    On first sync, Costory backfills up to **12 months** of PayGo usage, depending on what Cloudflare retains. New data then follows the usual [data refresh](/docs/data-refresh) cadence. SaaS sources typically appear in about **10 minutes**.
  </Tab>

  <Tab title="Terraform">
    Not supported yet.
  </Tab>
</Tabs>

## Field reference

| Field               | Required | Description                                                                  |
| ------------------- | -------- | ---------------------------------------------------------------------------- |
| **Connection name** | Yes      | Label in **Integrations**.                                                   |
| **API token**       | Yes      | Token with **Account / Billing / Read**. Stored in Costory's secret manager. |
| **Account ID**      | Yes      | 32-character Cloudflare account id.                                          |
| **Start date**      | No       | Optional start of the first sync. Leave empty for the default lookback.      |

## What Costory includes

Costory pulls PayGo billable usage from Cloudflare's [usage API](https://developers.cloudflare.com/api/resources/billing/subresources/usage/methods/get_account_usage_info_v1/) and maps it into [Standard Columns](/docs/standard-columns).

Typical lines include usage for PayGo products on that account (Workers, R2, and other products Cloudflare returns on the usage API).

**How to analyze Cloudflare costs**

* Spend by product: group by **Service name** or **SKU**
* Spend over time: use the same date presets as other billing sources in Explorer

**What Costory does not include**

* Enterprise contract invoices and committed-use billing (not on the public PayGo API)
* Taxes, credits, or invoice adjustments outside the usage API
* Zone-level analytics that are not billed on PayGo usage

<Info>
  Rotate the API token from **Integrations** when you need a new credential. The Account ID stays the same.
</Info>

## Troubleshooting

| Issue                                     | What to check                                                                                                                      |
| ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| Failed to authenticate                    | Confirm you pasted an **API token**, not a Global API key or Origin CA key. Recreate the token with **Account / Billing / Read**.  |
| Account not found                         | Confirm the **Account ID** is 32 hex characters from Overview, not a zone id.                                                      |
| Coverage / access denied                  | The account is not on PayGo. Enterprise contract billing is not available yet.                                                     |
| Validation succeeds but Explorer is empty | Wait for the first sync (about 10 minutes). Check the datasource date range on [Integrations](https://app.costory.io/integration). |

## Related pages

<CardGroup>
  <Card title="Billing Data" icon="database" href="/setup/billing">
    All billing providers and shared setup notes.
  </Card>

  <Card title="Explorer" icon="chart-line" href="/features/cost-explorer">
    Filter and group Cloudflare spend with the rest of your stack.
  </Card>

  <Card title="Standard Columns" icon="book" href="/docs/standard-columns">
    Normalized cost fields across providers.
  </Card>

  <Card title="Scaleway billing" icon="server" href="/setup/billing/scaleway">
    Import Scaleway consumption the same way.
  </Card>
</CardGroup>


# Confluent Billing Setup
Source: https://docs.costory.io/setup/billing/confluent

Connect Confluent Cloud billing data to Costory.

<Tabs>
  <Tab title="Terraform">
    Not supported.
  </Tab>

  <Tab title="Manual setup">
    Open Costory and go to **Billing > Import new billing datasource > Confluent**. The stepper guides you through each field.

    1. Create a Confluent Cloud API key and secret with billing access.
    2. Provide the API key and secret. Costory provisions the connection and starts syncing.

    On first sync, Costory backfills up to **12 months** of historical data (depending on your Confluent account).
  </Tab>
</Tabs>

**What Costory includes**

* **Invoice-level billing** from Confluent Cloud.
* **Per-cluster and per-environment cost breakdown** (group by **Resource name** or **Sub account id**).

**What Costory does not include**

* **Confluent Platform (self-managed)** costs. Only Confluent Cloud is supported.
* **Support or professional services fees** outside the invoice API.


# Cursor Billing Setup
Source: https://docs.costory.io/setup/billing/cursor

Connect Cursor usage and billing data to Costory via Admin API key or Terraform.

<Tabs>
  <Tab title="Terraform">
    ```hcl theme={null}
    terraform {
      required_providers {
        costory = {
          source  = "costory-io/costory"
          version = ">= 0.1.0"
        }
      }
    }

    variable "costory_api_token" {
      type        = string
      description = "Costory API token."
      sensitive   = true
    }

    variable "cursor_admin_api_key" {
      type        = string
      description = "Cursor admin API key used to fetch billing data."
      sensitive   = true
    }

    provider "costory" {
      token = var.costory_api_token
    }

    resource "costory_billing_datasource_cursor" "main" {
      name          = "Cursor Billing"
      admin_api_key = var.cursor_admin_api_key
    }
    ```
  </Tab>

  <Tab title="Manual setup">
    Open Costory and go to **Billing > Import new billing datasource > Cursor**. The stepper guides you through each field.

    1. Generate a **Cursor Admin API key** in your organization admin settings (Billing or API keys).
    2. Provide a datasource name and the **Admin API key** in the Costory stepper.

    On first sync, Costory backfills up to **12 months** of historical usage data.
  </Tab>
</Tabs>

**What Costory includes**

* **Chargeable usage events** only (Cursor marks these as chargeable).
* **Per-user spend** using the `user_email` from Cursor.
* **Per-model usage** (group by **Service name** = model).
* **Feature-level breakdown** using `kind`, `max_mode`, and `is_headless`.

**What Costory does not include**

* **Non-chargeable or included usage** (e.g., free or bundled allowances).
* **Seat or license invoices** that are not emitted as usage events.
* **Taxes or adjustments** outside the usage event stream.

**How to analyze Cursor costs**

* **Per-user email spend:** group by **Resource name** or **Sub account id**
  (both map to the Cursor user email).
* **Per-model costs:** group by **Service name** (model) and break down by
  **SKU** (`input` vs `output` tokens).
* **Feature usage:** group by the `kind`, `max_mode`, and `is_headless` labels to
  compare Compose vs Chat, Max mode usage, or headless runs.

<Note>
  Cursor costs are attributed to **input tokens**. Output token rows are
  included for usage analysis but have \$0 cost.
</Note>


# Datadog Billing Setup
Source: https://docs.costory.io/setup/billing/datadog

Connect Datadog usage and billing estimates to Costory.

Costory connects to Datadog billing with a Datadog API key and application key. It uses Datadog usage endpoints and billing endpoints to convert Datadog product usage into cost rows in [Explorer](/features/cost-explorer).

If you also want to query operational metrics from Datadog, see [Datadog usage metrics](/setup/usage-metrics/datadog).

<Tabs>
  <Tab title="Terraform">
    Not supported.
  </Tab>

  <Tab title="Manual setup">
    Open Costory, go to [Integrations](https://app.costory.io/integration), click **+ Add integration**, then choose **Datadog**. Pick **Billing / spend in Costory**. The stepper guides you through each field.&#x20;

    1. Generate a Datadog API key and application key with the following permissions:
       * `usage_read` (required): read Datadog product usage volumes.
       * `billing_read` (required): access the billing endpoints Costory uses for cost estimates.
       * `timeseries_query` (optional): query Datadog metrics when the same integration is used for usage metrics.
       * `ci_visibility_read` (optional): query Datadog CI visibility metrics.
    2. Enter the API key and application key in the Costory stepper. Costory tests the connection and starts syncing.
    3. If Datadog billing data does not appear after **24 hours**, see [Missing marketplace billing data](#missing-marketplace-billing-data).

    On first sync, Costory backfills up to **12 months** of historical usage data.
  </Tab>
</Tabs>

## Data Costory imports

Costory maps Datadog billing rows into [Standard Columns](/docs/standard-columns), so you can compare Datadog spend with AWS, GCP, Azure, and other billing datasources.

Costory includes:

* Usage-based billing estimates across Datadog products, including infrastructure, APM, logs, and similar usage lines.
* Per-product cost breakdowns. In **Explorer**, group by **Service name** to review each Datadog product.
* Historical usage data for trend analysis.

Costory does not include:

* Final Datadog invoices, taxes, credits, or support fees that Datadog does not expose through its billing and usage APIs.
* Contract-specific pricing terms that are not available through the Datadog APIs.
* Custom metrics pricing beyond what the Datadog usage API exposes.

## Why billing\_read matters

Usage APIs tell Costory what you used; billing APIs provide the cost context needed to turn that usage into billing rows. An API key can pass `usage_read` and `timeseries_query` checks while the billing endpoints stay blocked, in which case Costory reads usage but cannot map it into costs.

## API reference

Costory calls these [Datadog Usage Metering API](https://docs.datadoghq.com/api/latest/usage-metering/) endpoints. The base URL depends on your Datadog site (for example `https://api.datadoghq.com` for US1). Costory sends your API key and application key on every request.

| Use case                                  | Endpoint                            | Required scope |
| ----------------------------------------- | ----------------------------------- | -------------- |
| Usage volumes by product family           | `GET /api/v2/usage/hourly_usage`    | `usage_read`   |
| Current and previous month cost estimates | `GET /api/v2/usage/estimated_cost`  | `billing_read` |
| Historical monthly costs                  | `GET /api/v2/usage/historical_cost` | `billing_read` |

`hourly_usage` returns usage measurements (for example host counts, log volume) that Costory uses to build usage context. `estimated_cost` covers the current and previous month, with data delayed by up to 72 hours. `historical_cost` covers earlier months and is typically available by the 16th of the following month.

<Note>
  Billing endpoints (`estimated_cost`, `historical_cost`) may return **403 Forbidden** even when `usage_read` works. This is common for accounts billed through AWS Marketplace or GCP Marketplace. See [Missing marketplace billing data](#missing-marketplace-billing-data).
</Note>

## Missing marketplace billing data

In rare cases, customers who subscribe to Datadog through AWS Marketplace or GCP Marketplace cannot access Datadog billing data through Costory's Datadog connector.

The connector can still access usage and timeseries data, but Datadog billing data does not appear in Costory after **24 hours**. This means Costory can see what was used, but cannot create Datadog billing rows because the `billing_read` scope is blocked or the billing endpoints are unavailable for the account.

This is account-specific and does not mean every <Tooltip href="/docs/glossary#marketplace-purchases">marketplace subscription</Tooltip> has the same limitation. Datadog support can usually confirm the exact reason quickly. If the issue is a Datadog-side bug, they may also provide a workaround that Costory can implement.

Use this checklist before contacting Datadog support:

1. Confirm the application key user has the `billing_read` scope in Datadog.
2. Confirm the API key and application key belong to the Datadog site you selected in Costory.
3. Ask Datadog support why `billing_read` is blocked for your account.

You can send Datadog support this message:

```text theme={null}
We granted usage_read, timeseries_query, and billing_read to the Datadog application key used by Costory.

Usage and timeseries data is available in Costory, but Datadog billing data is still missing after 24 hours.

Why is billing_read blocked for our account?

Could this be related to how our Datadog subscription is linked through AWS Marketplace or GCP Marketplace?

If this is a Datadog-side bug, is there a supported workaround that Costory can implement?
```

If Datadog confirms that Billing APIs are unavailable for the account, Costory cannot ingest Datadog billing from that key. You can still use [Datadog usage metrics](/setup/usage-metrics/datadog) as non-cost metrics, but they will not create Datadog cost rows.

## Related

<CardGroup>
  <Card title="Billing Data overview" icon="database" href="/setup/billing">
    Review all billing datasources and shared setup concepts.
  </Card>

  <Card title="Datadog usage metrics" icon="chart-line" href="/setup/usage-metrics/datadog">
    Query Datadog timeseries metrics for allocation and analysis.
  </Card>

  <Card title="Explorer" icon="chart-simple" href="/features/cost-explorer">
    Explore Datadog costs with the rest of your billing data.
  </Card>

  <Card title="Standard Columns" icon="book" href="/docs/standard-columns">
    See how Datadog fields map into Costory's normalized schema.
  </Card>
</CardGroup>


# Elastic Cloud Billing Setup
Source: https://docs.costory.io/setup/billing/elastic-cloud

Connect Elastic Cloud organization billing to Costory with an Organization API key. Covers setup, historical sync, and what cost grain and dimensions you get in Explorer.

Costory pulls costs from the [Elastic Cloud Billing API](https://www.elastic.co/docs/api/doc/cloud-billing/) using your **Organization ID** and an **Elastic Cloud Organization API key**. Data is normalized into <Tooltip href="/docs/glossary#standard-columns">Standard Columns</Tooltip> so you can explore Elastic spend next to AWS, GCP, Azure, and other [billing datasources](/setup/billing).

After setup, Elastic Cloud costs behave like other billing data in **Explorer**: same filters, breakdowns, and saved views. The sections below cover what one row represents and which dimensions you can rely on.

<Tabs>
  <Tab title="Manual setup">
    Open Costory and go to **Billing > Import new billing datasource > Elastic Cloud**. The stepper guides you through each field.

    1. In the [Elastic Cloud Console](https://cloud.elastic.co/), open your organization and copy the **Organization ID** (you need it for the Costory form).

    <Frame>
      <img alt="Elastic Cloud console showing organization ID and API key management" />
    </Frame>

    2. Create an **Elastic Cloud Organization API key** with access to billing scope. Only organization owners can create these keys. See [Elastic Cloud API keys](https://www.elastic.co/docs/deploy-manage/api-keys/elastic-cloud-api-keys).
    3. In Costory, enter a datasource name, paste the **API key** and **Organization ID**, then submit. Validation calls the Billing API to confirm access.
    4. **Start Date** is optional. Use it to narrow the first sync window or cap the range Costory ingests. If you leave them empty, Costory uses its default initial backfill (see [Historical data](#historical-data)).

    On first sync, Costory backfills approximately **6 months** of historical billing data (one day at a time). Incremental syncs then keep data current.
  </Tab>

  <Tab title="Terraform / API">
    1. In the [Elastic Cloud Console](https://cloud.elastic.co/), copy your **Organization ID** and ensure you have an **Elastic Cloud Organization API key** with billing scope. Elastic does not provide Terraform resources for these credentials; create them in the console or via Elastic's APIs. See [Elastic Cloud API keys](https://www.elastic.co/docs/deploy-manage/api-keys/elastic-cloud-api-keys).

    <Frame>
      <img alt="Elastic Cloud console showing organization ID and API key management" />
    </Frame>

    2. Add the datasource to Costory with the [Costory Terraform provider](https://registry.terraform.io/providers/costory-io/costory/latest/docs):

    ```hcl theme={null}
    terraform {
      required_providers {
        costory = {
          source  = "costory-io/costory"
          version = ">= 0.1.0"
        }
      }
    }

    variable "costory_api_token" {
      type        = string
      description = "Costory API token."
      sensitive   = true
    }

    variable "elastic_cloud_api_key" {
      type        = string
      description = "Elastic Cloud API key used to fetch billing data."
      sensitive   = true
    }

    variable "elastic_cloud_organization_id" {
      type        = string
      description = "Elastic Cloud organization ID."
    }

    provider "costory" {
      token = var.costory_api_token
    }

    resource "costory_billing_datasource_elastic_cloud" "main" {
      name             = "Elastic Cloud Billing"
      api_key          = var.elastic_cloud_api_key
      organization_id  = var.elastic_cloud_organization_id
    }
    ```
  </Tab>
</Tabs>

## Data in Costory

Elastic sends one daily snapshot per **Elastic Cloud project**; Costory **expands** each project's `product_line_items` so that **one billing row is one product line** for that project and **usage day** (not a single rolled-up row per project per day).

**Dimensions and usage fields**

Each row below is a [Standard Column](/docs/standard-columns) in **Explorer** and breakdowns. Exports and advanced queries use the same names with a `cos_` prefix, for example **`cos_service_name`** for **Service name** and **`cos_consumed_quantity`** for **Consumed quantity**.

| Standard Column            | Filled from Elastic                                                        | Example                                                                                            |
| -------------------------- | -------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| **Provider**               | Fixed for this datasource.                                                 | `Elastic Cloud`                                                                                    |
| **Billing account id**     | Elastic **project id**.                                                    | `e9cc2fb04b35414690b77a3b2c593602`                                                                 |
| **Sub account id**         | Elastic **project name**.                                                  | `My Elasticsearch project`                                                                         |
| **Resource id**            | Same as **Billing account id** (project id).                               | `e9cc2fb04b35414690b77a3b2c593602`                                                                 |
| **Resource name**          | Same as **Sub account id** (project name).                                 | `My Elasticsearch project`                                                                         |
| **Service name**           | Full Elastic **product line label** for that billing line.                 | `Elasticsearch - General Purpose - Search VCU (GCP us-central1)`                                   |
| **SKU ID**                 | Elastic product line **sku** code.                                         | `elasticsearch.general-purpose-search-vcu_gcp-us-central1`                                         |
| **SKU Description**        | Same long label as **Service name** on that line.                          | `Elasticsearch - General Purpose - Search VCU (GCP us-central1)`                                   |
| **Region** / **Region id** | Parsed from the SKU when Elastic adds a cloud/region suffix.               | `gcp-us-central1` when the SKU ends with `_gcp-us-central1`; support lines may leave region empty. |
| **Category**               | Elastic line **`type`** (usage vs support, workload shape).                | `VCU`, `Search AI Lake`, or `support`                                                              |
| **Consumed quantity**      | **`quantity.value`** on the product line.                                  | `0.0016008`                                                                                        |
| **Consumed unit**          | **`unit`** on the product line (often matches **Category** for VCU lines). | `VCU`                                                                                              |
| **Pricing quantity**       | Same value as **Consumed quantity** for this datasource.                   | `0.0016008`                                                                                        |
| **Pricing unit**           | Same value as **Consumed unit** for this datasource.                       | `VCU`                                                                                              |

**Examples: Service name, SKU ID, and Category on the same billing line**

These are illustrative values Elastic may return; your org’s strings can differ.

* **Search VCU (regional usage)**
  * **Service name** / **SKU Description:** `Elasticsearch - General Purpose - Search VCU (GCP us-central1)`
  * **SKU ID:** `elasticsearch.general-purpose-search-vcu_gcp-us-central1`
  * **Category:** `VCU`
  * **Consumed quantity** / **Pricing quantity:** `0.0016008`
  * **Consumed unit** / **Pricing unit:** `VCU`

* **Retained storage**
  * **Service name** / **SKU Description:** Elastic’s full label for that storage line (same style as other product lines).
  * **SKU ID:** `elasticsearch.retained_gcp-us-central1`
  * **Category:** Depends on Elastic’s `type` for that line (for example storage-related).

* **Support (often zero rate)**
  * **Service name** / **SKU Description:** Elastic’s label for the support tier.
  * **SKU ID:** `serverless.support-tier1`
  * **Category:** `support`

## API reference

Costory calls Elastic's instance costs endpoint (see [Get costs for instances](https://www.elastic.co/docs/api/doc/cloud-billing/operation/operation-getcostsbyinstancesv2)):

`GET https://cloud.elastic.co/api/v2/billing/organizations/{organization_id}/costs/instances`

Authentication uses an API key in the `Authorization` header. See [Elastic Cloud API keys](https://www.elastic.co/docs/deploy-manage/api-keys/elastic-cloud-api-keys) and the [Elastic Cloud Billing API](https://www.elastic.co/docs/api/doc/cloud-billing/) for details.

## Field reference

| Field               | Required | Description                                                                             |
| ------------------- | -------- | --------------------------------------------------------------------------------------- |
| **API key**         | Yes      | Elastic Cloud Organization API key with Billing API access. Stored securely by Costory. |
| **Organization ID** | Yes      | Identifier of your Elastic Cloud organization.                                          |
| **Start Date**      | No       | Optional start of the range for the initial sync (ISO 8601).                            |
| **End Date**        | No       | Optional end of the sync range (ISO 8601).                                              |

## Historical data

**What Costory includes**

* **Product-line-level costs** for Elastic Cloud **projects** in your organization: each row is a **project** × **usage day** × **product line** (see [Data in Costory](#data-in-costory)).
* **Deployments** Elastic bills through the org (for example Elasticsearch and other Elastic Cloud project types returned by the API).
* **SKUs and service names** from Elastic's billing lines, plus **region** when Elastic encodes it on the SKU.
* **ECU context** as **labels** on each line, and **USD** amounts aligned with Elastic line quantity × rate.

## Related

<CardGroup>
  <Card title="Billing Data overview" icon="database" href="/setup/billing">
    All supported billing providers and shared setup concepts.
  </Card>

  <Card title="Explorer" icon="chart-line" href="/features/cost-explorer">
    Explore Elastic Cloud costs with the rest of your stack.
  </Card>

  <Card title="Standard Columns" icon="book" href="/docs/standard-columns">
    Per-column Elastic mapping (open the **Elastic Cloud** tab in each section).
  </Card>

  <Card title="Dimensions" icon="tags" href="/features/tagging/dimensions">
    Map Elastic lines and labels to teams or products.
  </Card>
</CardGroup>


# Custom Billing Format (FOCUS) in BigQuery
Source: https://docs.costory.io/setup/billing/focus

Import any FOCUS-compliant billing data from a BigQuery table into Costory.

Import any billing data that follows the [FOCUS specification](https://focus.finops.org/) from a BigQuery table. This is useful for SaaS vendors or internal services that are not natively supported.

<Accordion title="Importable Columns">
  | Mapping Key                  | Output Column                  | Type                                      | Default             | Status       |
  | ---------------------------- | ------------------------------ | ----------------------------------------- | ------------------- | ------------ |
  | `billedCost`                 | `billed_cost`                  | FLOAT64                                   | NULL                | Optional     |
  | `contractedCost`             | `contracted_cost`              | FLOAT64                                   | NULL                | Optional     |
  | `billingAccountId`           | `billing_account_id`           | STRING                                    | NULL                | Optional     |
  | `billingCurrency`            | `billing_currency`             | STRING                                    | NULL                | Optional     |
  | `originalBillingCurrency`    | `original_billing_currency`    | STRING                                    | NULL                | Optional     |
  | `billingPeriodEnd`           | `billing_period_end`           | DATETIME                                  | NULL                | **Required** |
  | `billingPeriodStart`         | `billing_period_start`         | DATETIME                                  | NULL                | **Required** |
  | `chargeCategory`             | `charge_category`              | STRING                                    | NULL                | **Required** |
  | `chargeDescription`          | `charge_description`           | STRING                                    | NULL                | Optional     |
  | `chargeFrequency`            | `charge_frequency`             | STRING                                    | NULL                | Optional     |
  | `chargePeriodStart`          | `charge_period_start`          | TIMESTAMP                                 | NULL                | Optional     |
  | `chargePeriodEnd`            | `charge_period_end`            | TIMESTAMP                                 | NULL                | Optional     |
  | `commitmentDiscountCategory` | `commitment_discount_category` | STRING                                    | NULL                | Optional     |
  | `commitmentDiscountId`       | `commitment_discount_id`       | STRING                                    | NULL                | Optional     |
  | `commitmentDiscountType`     | `commitment_discount_type`     | STRING                                    | NULL                | Optional     |
  | `consumedQuantity`           | `consumed_quantity`            | FLOAT64                                   | NULL                | Optional     |
  | `consumedUnit`               | `consumed_unit`                | STRING                                    | NULL                | Optional     |
  | `effectiveCost`              | `effective_cost`               | FLOAT64                                   | NULL                | Optional     |
  | `invoiceIssuer`              | `invoice_issuer`               | STRING                                    | NULL                | Optional     |
  | `listCost`                   | `list_cost`                    | FLOAT64                                   | NULL                | Optional     |
  | `listUnitPrice`              | `list_unit_price`              | STRING                                    | NULL                | Optional     |
  | `pricingCategory`            | `pricing_category`             | STRING                                    | NULL                | Optional     |
  | `pricingQuantity`            | `pricing_quantity`             | FLOAT64                                   | NULL                | Optional     |
  | `pricingUnit`                | `pricing_unit`                 | STRING                                    | NULL                | Optional     |
  | `provider`                   | `provider`                     | STRING                                    | `"Custom BigQuery"` | Optional     |
  | `publisher`                  | `publisher`                    | STRING                                    | NULL                | Optional     |
  | `regionId`                   | `region_id`                    | STRING                                    | NULL                | Optional     |
  | `resourceId`                 | `resource_id`                  | STRING                                    | NULL                | Optional     |
  | `resourceName`               | `resource_name`                | STRING                                    | NULL                | Optional     |
  | `resourceType`               | `resource_type`                | STRING                                    | NULL                | Optional     |
  | `categoryFocus`              | `category_focus`               | STRING                                    | NULL                | Optional     |
  | `serviceName`                | `service_name`                 | STRING                                    | NULL                | Optional     |
  | `skuId`                      | `sku_id`                       | STRING                                    | NULL                | Optional     |
  | `sku`                        | `sku`                          | STRING                                    | NULL                | Optional     |
  | `skuPriceId`                 | `sku_price_id`                 | STRING                                    | NULL                | Optional     |
  | `subAccountId`               | `sub_account_id`               | STRING                                    | NULL                | Optional     |
  | `tags`                       | `labels`                       | ARRAY\<STRUCT\<key STRING, value STRING>> | NULL                | Optional     |
</Accordion>

<Tabs>
  <Tab title="Terraform">
    Not supported.
  </Tab>

  <Tab title="Manual setup">
    Open Costory and go to **Billing > Import new billing datasource > Custom Billing Format (FOCUS)**. The stepper guides you through each field.

    1. Prepare a BigQuery table in FOCUS format.
    2. Provide the BigQuery table path, provider name, and optional billing account ID and date range.
    3. Map the FOCUS columns to Costory fields during the import flow.

    Costory imports whatever date range exists in the BigQuery table. No separate backfill step is needed.
  </Tab>
</Tabs>


# GCP Billing Setup
Source: https://docs.costory.io/setup/billing/gcp

Connect GCP BigQuery billing export with detailed usage costs to Costory via Terraform or manual setup.

<Tabs>
  <Tab title="Terraform">
    ```hcl theme={null}
    terraform {
      required_providers {
        google = {
          source  = "hashicorp/google"
          version = ">= 5.0"
        }
        costory = {
          source  = "costory-io/costory"
          version = ">= 0.1.0"
        }
      }
    }
    variable "costory_api_token" {
      type        = string
      description = "Costory API token."
      sensitive   = true
    }
    provider "costory" {
      token = var.costory_api_token
    }
    data "costory_service_account" "current" {}

    locals {
      bigquery_roles = toset([
        "roles/bigquery.metadataViewer",
        "roles/bigquery.dataViewer",
      ])
      # Set the BigQuery project, dataset, and table IDs where your detailed billing data is exported.
      bigquery_project_id = "my-project"
      bigquery_dataset_id = "billing_export"
      bigquery_table_id   = "gcp_billing_export_v1_0123"
    }

    resource "google_bigquery_dataset_iam_member" "costory_access" {
      for_each   = local.bigquery_roles
      project    = local.bigquery_project_id
      dataset_id = local.bigquery_dataset_id
      role       = each.key
      member     = "serviceAccount:${data.costory_service_account.current.service_account}"
    }

    resource "costory_billing_datasource_gcp" "main" {
      name                = "GCP Billing Export"
      bq_uri              = "${local.bigquery_project_id}.${local.bigquery_dataset_id}.${local.bigquery_table_id}"
      is_detailed_billing = true
      depends_on          = [google_bigquery_dataset_iam_member.costory_access]
    }
    ```
  </Tab>

  <Tab title="Manual setup">
    In Costory, go to **Billing > Import new billing datasource > GCP** and follow the stepper. First prepare your GCP account:

    1. In the GCP Billing console, enable **Detailed Usage Cost** export to BigQuery. Use **EU** as the dataset location (or create an EU replica).
    2. If you run GKE (autopilot or standard), enable **cost allocation** in the GKE cluster settings for pod-level Kubernetes cost visibility. See [Kubernetes cost visibility](/use-cases/k8s_waste/visibility) for details.
    3. Note the full table path (e.g., `gcp_billing_export_resource_v1_<billing_account_id>`). GCP automatically includes all resource labels in the billing export, so no extra tag activation is needed.
    4. Share the BigQuery dataset with the Costory service account using **BigQuery Data Viewer** and **BigQuery Metadata Viewer** roles. You can find the service account in Costory under **Billing > Import new billing datasource > GCP**.
    5. In Costory, go to **Billing > Import new billing datasource > GCP** and provide the table path.

    <Note>
      GCP backfills only the previous and the current month by default.
    </Note>
  </Tab>
</Tabs>


# GCP CUD Metadata
Source: https://docs.costory.io/setup/billing/gcp-cud-metadata

Import GCP Committed Use Discount metadata from BigQuery into Costory.

<Tabs>
  <Tab title="Terraform">
    Not supported.
  </Tab>

  <Tab title="Manual setup">
    Open Costory and go to **Billing > Import new billing datasource > GCP CUD Metadata**. The stepper guides you through each field.

    1. Export GCP Committed Use Discount metadata to BigQuery.
    2. Ensure the table includes required columns:
       * billing\_account\_id, cud\_product, consumption\_model, subscription, region,
         term, start\_time, end\_time, state
    3. Provide the BigQuery table path in the Costory stepper.

    Reference:\
    [https://cloud.google.com/billing/docs/how-to/export-data-bigquery-tables/cud-export](https://cloud.google.com/billing/docs/how-to/export-data-bigquery-tables/cud-export)
  </Tab>
</Tabs>

**What Costory includes**

* **Commitment metadata**: billing account, product, region, term, start/end dates, and state.
* **Consumption model and subscription type** for each commitment.

**What Costory does not include**

* **Commitment cost or savings data**. This datasource provides metadata only. Actual CUD cost impact is captured in the [GCP billing export](/setup/billing/gcp).
* No historical backfill. Costory imports the current state of the BigQuery table.


# OpenAI Billing Setup
Source: https://docs.costory.io/setup/billing/openai

Connect OpenAI organization costs to Costory with a read-only Admin API key. Import Platform API usage into Explorer next to AWS, GCP, and Azure.

OpenAI Platform spend sits on a separate bill from AWS, GCP, and Azure. Connect with a **read-only Admin API key** so organization costs land in <Tooltip href="/docs/glossary#cost-explorer">Explorer</Tooltip> with your other [billing datasources](/setup/billing).

This connector imports **OpenAI Platform (API usage)** organization costs from the [Costs API](https://developers.openai.com/api/reference/resources/admin/subresources/organization/subresources/usage/methods/costs). Costory stores them as a billing datasource, the same as other SaaS billing sources.

<Info>
  Azure OpenAI (Cognitive Services) is billed through Azure. Use the [Azure billing connector](/setup/billing/azure) for that spend. ChatGPT Enterprise and Codex are not on this connector.
</Info>

<Tabs>
  <Tab title="Manual setup">
    <Steps>
      <Step title="Create an Admin API key">
        In [OpenAI Platform > Settings > Admin keys](https://platform.openai.com/settings/organization/admin-keys), create an **Admin API key** (`sk-admin-...`). You must be an organization **admin**. A project inference key (`sk-...` or `sk-proj-...`) will not work. Copy the key immediately. It is shown once.
      </Step>

      <Step title="Grant read-only scopes">
        Grant **read-only** scopes only. Do not grant write.

        | Scope                   | API id                | Required                                                                                      |
        | ----------------------- | --------------------- | --------------------------------------------------------------------------------------------- |
        | **Usage**               | `api.usage.read`      | Yes. Costory cannot ingest spend without it.                                                  |
        | **API keys + Projects** | `api.management.read` | Recommended. Without it, spend still lands, but key, user, and project names stay as raw ids. |
      </Step>

      <Step title="Connect in Costory">
        Go to [Integrations](https://app.costory.io/integration), click **+ Add integration**, then choose **OpenAI** under **Billing**. The connect URL is `/integration/new/openai/billing`.&#x20;
      </Step>

      <Step title="Enter connection details">
        Fill **Connection name** (default **OpenAI**) and **Admin API key**. **Start date** is optional. Leave it empty to use Costory's default lookback.
      </Step>

      <Step title="Validate, then save">
        Click **Validate**. Costory calls `GET /v1/organization/costs` with `Authorization: Bearer`. **Save** stays disabled until the Admin key can read organization costs. If this is the only billing source and it is demo data, Costory asks you to confirm before replacing it.
      </Step>
    </Steps>

    On first sync, Costory backfills up to **12 months** of organization costs, depending on what OpenAI retains. New data then follows the usual [data refresh](/docs/data-refresh) cadence. SaaS sources typically appear in about **10 minutes**.
  </Tab>

  <Tab title="Terraform">
    Not supported yet.
  </Tab>
</Tabs>

## Field reference

| Field               | Required | Description                                                                                      |
| ------------------- | -------- | ------------------------------------------------------------------------------------------------ |
| **Connection name** | Yes      | Label in **Integrations**.                                                                       |
| **Admin API key**   | Yes      | Organization Admin key (`sk-admin-...`) with **Usage** read. Stored in Costory's secret manager. |
| **Start date**      | No       | Optional start of the first sync. Leave empty for the default lookback.                          |

## What Costory includes

Costory pulls organization costs from OpenAI's Costs API and maps them into <Tooltip href="/docs/glossary#standard-columns">Standard Columns</Tooltip>.

Typical lines include billed Platform usage for that organization (models, line items, and the project or API key OpenAI returns on the Costs API).

**How to analyze OpenAI costs**

* Spend by project: one OpenAI **project** (and project key) per team is the split the Costs API exposes. Map those projects onto a [virtual dimension](/features/tagging/dimensions) for showback. See [Allocate LLM cost per team](/use-cases/llm-ai-cost).
* Spend by model or line item: group by **Service name** or **SKU**
* Spend by API key or user: names appear when the key has **API keys + Projects** read. Otherwise you see raw ids.

**What Costory does not include**

* Azure OpenAI charges (use the [Azure connector](/setup/billing/azure))
* ChatGPT Enterprise or Codex billing
* Taxes, credits, or invoice adjustments outside the Costs API
* Per-request application metadata (feature, route, customer). OpenAI's export does not carry those labels.

<Info>
  Rotate the Admin API key from **Integrations** when you need a new credential. Keep **Usage** read on the replacement key.
</Info>

## Troubleshooting

| Issue                                     | What to check                                                                                                                                                                     |
| ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Failed to authenticate                    | Confirm you pasted an **Admin API key** (`sk-admin-...`), not a project inference key. Recreate it in [Admin keys](https://platform.openai.com/settings/organization/admin-keys). |
| Access denied                             | Grant **Usage** (`api.usage.read`) on a **read-only** Admin key.                                                                                                                  |
| Costs API endpoint not found              | Confirm the Admin API is enabled for this organization and that you are an organization admin.                                                                                    |
| Spend lands, names are raw ids            | Add **API keys + Projects** (`api.management.read`). Costory does not block save when this scope is missing.                                                                      |
| Validation succeeds but Explorer is empty | Wait for the first sync (about 10 minutes). Check the datasource date range on [Integrations](https://app.costory.io/integration).                                                |

## Related pages

<CardGroup>
  <Card title="Billing Data" icon="database" href="/setup/billing">
    All billing providers and shared setup notes.
  </Card>

  <Card title="Anthropic billing" icon="robot" href="/setup/billing/anthropic">
    Connect Anthropic Claude Console and claude.ai costs.
  </Card>

  <Card title="Allocate LLM cost per team" icon="sitemap" href="/use-cases/llm-ai-cost">
    Split OpenAI, Anthropic, and cloud LLM spend by team.
  </Card>

  <Card title="Explorer" icon="chart-line" href="/features/cost-explorer">
    Filter and group OpenAI spend with the rest of your stack.
  </Card>
</CardGroup>


# Scaleway Billing Setup
Source: https://docs.costory.io/setup/billing/scaleway

Connect Scaleway cloud billing to Costory with an IAM secret key and Organization ID. Import consumption by category, product, and project.

Scaleway Instances, Object Storage, and managed services often sit outside your main cloud bill. Connect with an IAM **secret key** and **Organization ID** so consumption lands in [Explorer](/features/cost-explorer) next to AWS, GCP, Azure, and other [billing datasources](/setup/billing).

<Tabs>
  <Tab title="Manual setup">
    <Steps>
      <Step title="Create an IAM application">
        In the [Scaleway console](https://console.scaleway.com/), create an IAM application. Attach the **BillingReadOnly** policy at **Organization** scope. See [Scaleway IAM API keys](https://www.scaleway.com/en/docs/identity-and-access-management/iam/how-to/create-api-keys/).
      </Step>

      <Step title="Create an API key">
        Create an API key for that application. Copy the **secret key** immediately. It is shown once. The **access key** is optional in Costory. Costory can store it, but the billing API authenticates with the secret key only.
      </Step>

      <Step title="Copy the Organization ID">
        Copy the **Organization ID** from the Organization dashboard.
      </Step>

      <Step title="Connect in Costory">
        Go to [Integrations](https://app.costory.io/integration), click **+ Add integration**, then choose **Scaleway** under **Billing**. The connect URL is `/integration/new/scaleway/billing`.&#x20;
      </Step>

      <Step title="Enter connection details">
        Fill **Connection name** (default **Scaleway**), **Secret key**, and **Organization ID**. **Access key** and **Start date** are optional. Leave **Start date** empty to use Costory's default lookback.
      </Step>

      <Step title="Validate, then save">
        Click **Validate**. Costory calls `GET /billing/v2beta1/consumptions` with `X-Auth-Token` set to the secret key. **Save** stays disabled until validation succeeds. If this is the only billing source and it is demo data, Costory asks you to confirm before replacing it.
      </Step>
    </Steps>

    On first sync, Costory backfills up to **12 months** of consumption, depending on what Scaleway retains. New data then follows the usual [data refresh](/docs/data-refresh) cadence. SaaS sources typically appear in about **10 minutes**.
  </Tab>

  <Tab title="Terraform">
    Not supported yet.
  </Tab>
</Tabs>

## Field reference

| Field               | Required | Description                                                                 |
| ------------------- | -------- | --------------------------------------------------------------------------- |
| **Connection name** | Yes      | Label in **Integrations**.                                                  |
| **Secret key**      | Yes      | IAM API secret. Sent as `X-Auth-Token`. Stored in Costory's secret manager. |
| **Organization ID** | Yes      | Scaleway organization the consumption API should query.                     |
| **Access key**      | No       | Stored with the secret if you paste it. The billing API does not use it.    |
| **Start date**      | No       | Optional start of the first sync. Leave empty for the default lookback.     |

## What Costory includes

Costory pulls monthly consumption from the [Scaleway Consumption API](https://www.scaleway.com/en/developers/api/billing/consumption) and maps it into [Standard Columns](/docs/standard-columns).

Typical lines include:

* Categories such as Compute, Storage, Network, Object Storage, Serverless, and Observability
* Product name and SKU (for example a VPC Public Gateway size)
* Project and resource names when Scaleway returns them
* Billed quantity, unit, and monetary value

**How to analyze Scaleway costs**

* Spend by product: group by **Service name** or **SKU**
* Spend by project: group by **Billing account id** or **Sub account id** when those fields carry the Scaleway project
* Spend by invoice category: group by **Category**

**What Costory does not include**

* Credits, promotional discounts, or tax lines that never appear on the consumption API
* Support or marketplace fees billed outside consumption
* Write access to your Scaleway organization. Costory only calls the billing read endpoint

<Info>
  Rotate the secret key from **Integrations** when you need a new credential. The Organization ID stays the same.
</Info>

## Troubleshooting

| Issue                                     | What to check                                                                                                                                     |
| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| Authentication fails                      | Recreate the API key and paste the **secret key**, not the access key. Confirm the IAM application has **BillingReadOnly** at Organization scope. |
| Organization not found                    | Confirm the **Organization ID** from the Organization dashboard, not a project ID.                                                                |
| Validation succeeds but Explorer is empty | Wait for the first sync (about 10 minutes). Check the datasource date range on [Integrations](https://app.costory.io/integration).                |

## Related pages

<CardGroup>
  <Card title="Billing Data" icon="database" href="/setup/billing">
    All billing providers and shared setup notes.
  </Card>

  <Card title="Explorer" icon="chart-line" href="/features/cost-explorer">
    Filter and group Scaleway spend with the rest of your stack.
  </Card>

  <Card title="Standard Columns" icon="book" href="/docs/standard-columns">
    Normalized cost fields across providers.
  </Card>

  <Card title="Cloudflare billing" icon="cloud" href="/setup/billing/cloudflare">
    Import Cloudflare PayGo usage the same way.
  </Card>
</CardGroup>


# Snowflake Billing Setup
Source: https://docs.costory.io/setup/billing/snowflake

Connect Snowflake account usage and billing data to Costory using key-pair authentication and a reusable Snowflake integration.

Snowflake billing ingestion uses a **Snowflake integration** you create once on the **Integrations** page, then attach to a billing datasource. Authentication is **key-pair** (RSA): Costory shows a **public** key for your Snowflake user; the **private** key is stored securely and is never returned after you save.

<Tabs>
  <Tab title="Terraform">
    Not supported yet.
  </Tab>

  <Tab title="Manual setup">
    ### 1. Create the Snowflake integration

    1. Open Costory and go to **Integrations**.
    2. Start the flow to add a **Snowflake** integration.
    3. When Costory displays **setup SQL** and a generated **public RSA key**, copy them.
    4. In the Snowflake console (or worksheet), run the setup SQL as a user who can alter the login for the Snowflake user Costory will use. This registers the public key for key-pair authentication.
    5. Enter the Snowflake connection details Costory asks for (for example account identifier, user, role, and warehouse as shown in the stepper).
    6. Complete validation. Costory checks access through the **Snowflake SQL API** before any sync is enabled.

    ### 2. Enable Snowflake billing

    1. Go to **Billing** > **Import new billing datasource** > **Snowflake**.
    2. Select the **Snowflake integration** you created above.
    3. Finish the stepper. Costory provisions the billing sync and starts ingesting data.

    First sync timing is similar to other SaaS billing sources (on the order of **minutes**). See [Data refresh](/docs/data-refresh) for ongoing cadence.
  </Tab>
</Tabs>

**What Costory includes**

* **Usage-based cost data** from Snowflake account usage (including views such as **USAGE\_IN\_CURRENCY\_DAILY**), with **warehouse** and **query** history where the connector exposes them for allocation and analysis. **Query tags** are included when Snowflake provides them, so query-level costs appear with tag dimensions you can use to filter and group in [Explorer](/features/cost-explorer).

**What Costory does not include**

* **Terraform** automation for this datasource (use the UI only until Terraform support ships).

<Info>
  To remove access, delete or rotate credentials from the Costory UI and adjust Snowflake users and keys on your side. You cannot archive a Snowflake integration while an active billing datasource still references it.
</Info>

## Related

* [Billing Data](/setup/billing): overview of all billing sources
* [Snowflake Metrics](/setup/usage-metrics/snowflake): query tables from another database on the same integration
* [Standard Columns](/docs/standard-columns): normalized cost fields across providers
* [Explorer](/features/cost-explorer): explore ingested costs after sync


# Email
Source: https://docs.costory.io/setup/collaboration/email

Configure email delivery in Costory for scheduled cloud cost reports and alert notifications.

Send cloud cost updates by email to individuals or distribution lists.

Email delivery works with:

* Scheduled reports from [Cost Reports](/features/slack-reports)
* Threshold notifications from [cloud cost alerts](/features/alerts)
* Periodic summaries from [Digest](/features/digest)

## Prerequisites

* Access to Costory with permission to create reports or alerts.
* Valid recipient email addresses, shared mailboxes, or distribution lists.

## Configure email for scheduled reports

<Steps>
  <Step title="Open a saved view in Explorer">
    Create or select the saved view you want to send on a schedule.
  </Step>

  <Step title="Start report scheduling">
    Click **Schedule Report** and choose **Email** as the destination channel.
  </Step>

  <Step title="Add recipients">
    Enter one or more email recipients and set cadence, period, and comparison
    options.
  </Step>

  <Step title="Send a test report">
    Send a test email to confirm delivery and verify the report format.
  </Step>

  <Step title="Save the schedule">
    Save the configuration so Costory sends reports automatically on the
    selected cadence.
  </Step>
</Steps>

## Configure email for alerts

<Steps>
  <Step title="Create or edit an alert">
    Go to **Alerts** and open the alert configuration you want to notify from.
  </Step>

  <Step title="Choose email as notification channel">
    In notification settings, select **Email** and add recipients.
  </Step>

  <Step title="Set frequency and severity routing">
    Configure how often notifications are sent and which conditions trigger
    delivery.
  </Step>

  <Step title="Validate with a test">
    Send a test notification before activating the alert.
  </Step>
</Steps>

## Delivery best practices

* Use distribution lists so recipients stay in one place to manage.
* Scope recipients by role to keep updates relevant.
* Review recipient lists quarterly and remove inactive addresses.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Can I send to multiple recipients?">
    Yes. Add multiple addresses or a distribution list when configuring the
    report or alert.
  </Accordion>

  <Accordion title="Can email and Slack or Teams be used together?">
    Yes. You can create multiple schedules or notification targets for the same
    view or alert.
  </Accordion>

  <Accordion title="Who receives alert emails by default?">
    Alert recipients are defined in each alert configuration. There is no single
    global default list.
  </Accordion>

  <Accordion title="What should I do if emails are not received?">
    Verify recipient addresses, check spam or quarantine rules, and send a new
    test from Costory.
  </Accordion>
</AccordionGroup>

## Related setup guides

<CardGroup>
  <Card title="Set Up Slack Integration" icon="slack" href="/setup/collaboration/slack">
    Deliver updates to Slack channels and direct conversations.
  </Card>

  <Card title="Set Up Teams Integration" icon="microsoft" href="/setup/collaboration/teams">
    Deliver updates to Microsoft Teams channels.
  </Card>

  <Card title="Cost Reports" icon="file-chart-line" href="/features/slack-reports">
    Build and schedule recurring reports.
  </Card>

  <Card title="Cloud cost alerts" icon="triangle-exclamation" href="/features/alerts">
    Configure threshold-based notifications.
  </Card>
</CardGroup>


# Slack
Source: https://docs.costory.io/setup/collaboration/slack

Configure the Costory Slack integration to send scheduled cost reports and alerts to your Slack channels.

Connect Costory to Slack to deliver cost reports, alerts, and digest summaries to your channels.

Use this setup to deliver:

* Scheduled reports from [Cost Reports](/features/slack-reports)
* Notifications from [cloud cost alerts](/features/alerts)
* Digest summaries from [Digest](/features/digest)

## Prerequisites

* A Costory organization with at least one active user.
* A **Slack Workspace Administrator** invited to your Costory organization.
* Access to the **Integrations** page in the Costory app.

## Recommended: create a dedicated channel

Before installation, create one or more channels for cloud cost updates, for example `#cloud-cost-updates`.

Include the people who need recurring visibility:

* Engineering
* DevOps or platform teams
* Finance or FinOps stakeholders

## Install the Costory Slack app

<Steps>
  <Step title="Open the Costory integration page">
    Sign in to Costory and open **Integrations** in the Costory app.
  </Step>

  <Step title="Start Slack installation">
    Select **Slack** and click the install action to open the Slack
    authorization screen.
  </Step>

  <Step title="Review requested permissions">
    Confirm the requested Slack scopes listed below.
  </Step>

  <Step title="Authorize and return to Costory">
    Click **Allow** in Slack, then return to Costory.
  </Step>

  <Step title="Add the Costory bot to target channels">
    In each Slack channel where you want updates, invite the bot with
    `@costory`.
  </Step>

  <Step title="Send a test notification">
    Back in Costory, refresh the integration page and send a test message to
    verify channel delivery.
  </Step>
</Steps>

## Slack scopes and why Costory requests them

| Scope              | Why Costory needs it                                                                                              |
| ------------------ | ----------------------------------------------------------------------------------------------------------------- |
| `chat:write`       | Send reports and alert messages to channels, direct messages, and group direct messages where the bot is present. |
| `commands`         | Support slash commands such as creating Costory events from Slack.                                                |
| `channels:read`    | Read public channel metadata so channel destinations can be selected.                                             |
| `groups:read`      | Read private channel metadata for channels where the bot has been invited.                                        |
| `im:read`          | Read direct message conversation metadata where the bot is present.                                               |
| `mpim:read`        | Read group direct message metadata where the bot is present.                                                      |
| `users:read`       | Read basic workspace user details for account mapping.                                                            |
| `users:read.email` | Match Costory users to Slack users by email address.                                                              |

<Info>
  Costory posts only where it is invited. It does not auto-join channels.
</Info>

<Tip>
  Once Slack is connected, ask the [Costory MCP](/features/mcp) from chat to schedule a report or create an alert that posts to a channel.
</Tip>

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Can Costory read all messages in our Slack workspace?">
    No. Costory works only in channels or conversations where the bot is
    explicitly present, and it is used for destination setup and notification
    delivery.
  </Accordion>

  <Accordion title="Who can install the Slack integration?">
    A Slack Workspace Administrator must authorize the Costory app.
  </Accordion>

  <Accordion title="Can we change channels later?">
    Yes. You can invite the bot to new channels and update destinations at any
    time.
  </Accordion>

  <Accordion title="Why is my channel missing in Costory?">
    Make sure the bot was invited to that channel, then refresh the integrations
    page in Costory.
  </Accordion>
</AccordionGroup>

## Related setup guides

<CardGroup>
  <Card title="Set Up Teams Integration" icon="microsoft" href="/setup/collaboration/teams">
    Configure Microsoft Teams as a destination.
  </Card>

  <Card title="Set Up Email Delivery" icon="envelope" href="/setup/collaboration/email">
    Send reports and alerts to email recipients.
  </Card>

  <Card title="Cost Reports" icon="file-chart-line" href="/features/slack-reports">
    Schedule recurring cost reports.
  </Card>

  <Card title="Cloud cost alerts" icon="triangle-exclamation" href="/features/alerts">
    Send threshold-based notifications.
  </Card>
</CardGroup>


# Microsoft Teams
Source: https://docs.costory.io/setup/collaboration/teams

Configure the Costory Microsoft Teams integration to send scheduled reports and alerts to Teams channels.

Connect Costory to Microsoft Teams to send scheduled reports and alert notifications to Teams channels.

Use this setup to deliver:

* Scheduled reports from [Cost Reports](/features/slack-reports)
* Notifications from [cloud cost alerts](/features/alerts)
* Digest summaries from [Digest](/features/digest)

## Current availability

While Microsoft certification is in progress, the Costory Teams app is distributed through the **Integrations** page in the Costory app. Download the app package and connect your organization there.

## Prerequisites

* A Microsoft 365 tenant where your organization uses Teams.
* Access to install or upload an app package in your tenant.
* Access to the Costory integration page.

<Warning>
  Some tenants restrict custom app uploads. If upload is blocked, ask your
  Microsoft 365 administrator to allow the app package for your organization.
</Warning>

## Install and connect Teams

<Steps>
  <Step title="Open Integrations in Costory">
    Go to `Costory Integrations page` and select **Microsoft Teams**.
  </Step>

  <Step title="Download the Teams app package">
    Download the provided `.zip` package from the integration screen.
  </Step>

  <Step title="Upload the package in Teams">
    In Microsoft Teams, use your app management flow to upload the Costory app
    package.
  </Step>

  <Step title="Authorize and link your tenant">
    Complete the connection flow shown in Costory so your Teams workspace is
    linked.
  </Step>

  <Step title="Choose destination channels">
    Select the Teams channels that should receive reports or alerts.
  </Step>

  <Step title="Send a test message">
    Trigger a test delivery from Costory to confirm channel access and message
    rendering.
  </Step>
</Steps>

## Use Teams as a destination

Once connected, select a Teams channel as the destination in:

* Cost Reports, when scheduling recurring reports from saved views
* Alerts, when choosing notification channels for thresholds and anomalies

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Can we use Teams for both scheduled reports and alerts?">
    Yes. Teams channels can be used in both report schedules and alert
    notifications.
  </Accordion>

  <Accordion title="Do we need global admin rights to install the app?">
    It depends on your tenant policy. Some organizations allow app upload by
    team owners, while others require a Microsoft 365 admin.
  </Accordion>

  <Accordion title="Can we change destination channels later?">
    Yes. You can update channel selections at any time in Costory.
  </Accordion>

  <Accordion title="What if the app package is rejected?">
    Check tenant app permissions and upload policy, then retry. If needed,
    contact Costory support with the Teams error message.
  </Accordion>
</AccordionGroup>

## Related setup guides

<CardGroup>
  <Card title="Set Up Slack Integration" icon="slack" href="/setup/collaboration/slack">
    Configure Slack channels for delivery.
  </Card>

  <Card title="Set Up Email Delivery" icon="envelope" href="/setup/collaboration/email">
    Send reports and alerts to email recipients.
  </Card>

  <Card title="Cost Reports" icon="file-chart-line" href="/features/slack-reports">
    Schedule recurring cost reports.
  </Card>

  <Card title="Cloud cost alerts" icon="triangle-exclamation" href="/features/alerts">
    Configure proactive spend notifications.
  </Card>
</CardGroup>


# BigQuery Data Exports
Source: https://docs.costory.io/setup/destinations/bigquery

Set up BigQuery data exports in Costory so analysts can query dashboard widget data from Looker, notebooks, dbt, and custom SQL.

# BigQuery data exports

**BigQuery data exports** let Copilot Pro organizations query the cost data behind their dashboard widgets from their own BigQuery project. Use them to connect Looker, notebooks, dbt, or custom SQL without rebuilding dashboard filters by hand.

<Info>
  BigQuery data exports are available on Copilot Pro.
</Info>

## How it works

An **Organization Admin** configures access under **Integrations > Destinations**. After access is granted, analysts can copy SQL from any [dashboard](/features/dashboards) widget and run it against the Costory export table in BigQuery.

The copied SQL matches the dashboard widget configuration, including the metric, filters, group-by, and date range.

## Prerequisites

* A Costory organization on Copilot Pro
* **Organization Admin** access in Costory to manage **Integrations > Destinations**
* A BigQuery user or service account that should run the exported queries
* At least one [dashboard widget](/features/dashboards) with the cost view you want to query

## Grant access to the export table

<Steps>
  <Step title="Open Destinations">
    In Costory, go to **Integrations > Destinations**.
  </Step>

  <Step title="Open the BigQuery export destination">
    Select the BigQuery data export destination for your organization.
  </Step>

  <Step title="Grant read access">
    Add the BigQuery user or service account that should query the export table.
  </Step>

  <Step title="Save the destination">
    Save the destination settings. The user or service account can now run copied dashboard queries against the export table.
  </Step>
</Steps>

## Copy SQL from a dashboard widget

<Steps>
  <Step title="Open the dashboard">
    Open the [dashboard](/features/dashboards) that contains the widget you want to analyze outside Costory.
  </Step>

  <Step title="Open widget actions">
    Click the widget action menu.
  </Step>

  <Step title="Copy the query">
    Click **Copy SQL query**.
  </Step>

  <Step title="Run the query">
    Paste the SQL into BigQuery, Looker, a notebook, or another tool that can query BigQuery.
  </Step>
</Steps>

<Frame>
  <img alt="Copy SQL query action on a dashboard widget" />
</Frame>

## Permissions

| Permission                               | Who needs it                                | Why                                                            |
| ---------------------------------------- | ------------------------------------------- | -------------------------------------------------------------- |
| Costory **Organization Admin**           | The person configuring the destination      | Required to grant access under **Integrations > Destinations** |
| BigQuery read access to the export table | The user or service account running queries | Required to run copied SQL outside Costory                     |
| Dashboard access in Costory              | The person copying SQL                      | Required to open the widget and copy its query                 |

## FAQ

<AccordionGroup>
  <Accordion title="Does this replace billing data setup?">
    No. BigQuery data exports are for querying Costory data outside Costory. You still need to connect billing data first through [Billing Data](/setup/billing).
  </Accordion>

  <Accordion title="Can I copy SQL from Explorer?">
    The copy action is available on dashboard widgets. To reuse an Explorer query, save it as a dashboard widget first.
  </Accordion>

  <Accordion title="Does the SQL include dashboard filters?">
    Yes. The copied SQL matches the widget configuration, including filters, group-by, metric, and date range.
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup>
  <Card title="Dashboards" icon="chart-pie" href="/features/dashboards">
    Build the dashboard widgets you want to query from BigQuery
  </Card>

  <Card title="Billing Data" icon="database" href="/setup/billing">
    Connect cloud billing data before exporting Costory data
  </Card>
</CardGroup>


# Connect Engineering Events to Costory (GitHub, CI/CD, Custom API)
Source: https://docs.costory.io/setup/events

Save the cause of a cost change as an event linked to a dashboard, and push deploy events from CI/CD so Costory's AI analysis knows what you shipped.

You trace a cost spike to a nightly batch job, post the answer in Slack, and a month later someone asks about the same bump on the same chart. Events keep that work. Save the cause as an event, link it to the dashboard, and the explanation stays attached to the chart for the next person who opens it.

<Frame>
  <img alt="Costory dashboard contextualized with events on cost charts" />
</Frame>

## Two ways to use events

### Save an analysis instead of redoing it

When an investigation ends with a clear cause, [create a saved event](/features/events#create-a-saved-event-with-context) with your conclusion and add it to the relevant dashboard or [Explorer](/features/cost-explorer) view. Anyone who looks at the chart later sees the marker and the cause together, and the question stops coming back to you.

### Record a change before costs move

When you ship something that will affect spend (a new batch job, an instance migration, a commitment purchase), push an event from your pipeline at deploy time. It is a single `POST /v1/events` call. When the cost line moves a few days later, the context is already on the timeline, and Costory's AI analysis and agents connected through the [Costory MCP](/features/mcp) use it to explain the change rather than guessing at causes.

## Connect an event source

<CardGroup>
  <Card title="GitHub deploys" icon="github" href="/setup/events/github">
    PR merges and releases appear as deploy markers, with a link back to the PR.
  </Card>

  <Card title="CI/CD pipelines" icon="gear" href="/setup/events/ci-cd">
    Post an event from your deploy step with a single API call.
  </Card>

  <Card title="Custom API events" icon="calendar-plus" href="/setup/events/custom-api">
    Send incidents, migrations, campaigns, or anything else that explains spend.
  </Card>

  <Card title="Provider events" icon="cloud" href="/setup/events/provider">
    Commitment purchases detected automatically from billing data.
  </Card>
</CardGroup>

Provider events, such as <Tooltip href="/docs/glossary#savings-plans">Savings Plan</Tooltip> purchases, need no setup beyond connecting your billing data. AWS is live today, with Azure and GCP on the roadmap.

Once a source is connected, events show up on the [Events page](/features/events) and as overlays in [Explorer](/features/cost-explorer). See the [Events feature page](/features/events) for how to attach them to dashboards and reports.


# Send Events from CI/CD Pipelines
Source: https://docs.costory.io/setup/events/ci-cd

Post build and deploy events from your CI/CD pipelines to Costory using the Events API.

Post build and deploy events from your pipelines with a curl call to the Events API.

### Example: curl from a CI/CD pipeline

```bash theme={null}
curl -X POST "https://app-api.costory.io/events" \
  -H "Authorization: Bearer $COSTORY_EVENTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Deploy complete",
    "timestamp": "2026-03-04T14:25:00Z",
    "category": "TECHNICAL",
    "source": "ci-cd",
    "environment": "prod",
    "service": "api",
    "labels": ["release", "backend"],
    "metadata": {
      "commit": "1b2c3d4",
      "pipeline": "github-actions",
      "url": "https://github.com/acme/api/actions/runs/123"
    }
  }'
```

### Recommended event fields

| Field         | Required | Description                                             |
| ------------- | -------- | ------------------------------------------------------- |
| `name`        | Yes      | Event title shown in the timeline.                      |
| `timestamp`   | Yes      | ISO-8601 UTC timestamp for the event.                   |
| `category`    | Yes      | BUSINESS, TECHNICAL, or PROVIDER.                       |
| `source`      | Yes      | A short identifier like `custom`, `ci-cd`, or `github`. |
| `environment` | No       | `prod`, `staging`, or another environment label.        |
| `service`     | No       | Service or application name.                            |
| `labels`      | No       | Reusable tags for filtering in Costory.                 |
| `metadata`    | No       | JSON object with URLs, commit SHAs, or context.         |

<Tip>
  Use consistent labels and environments so filters work across teams. For example: `prod`, `staging`, `api`, `frontend`.
</Tip>


# Send Custom Events via API
Source: https://docs.costory.io/setup/events/custom-api

Send any event that explains cloud spend to Costory using the Events API and Python.

Send any event that explains spend via the Events API.

### Example: Python

```python theme={null}
import os
import requests

payload = {
    "name": "Incident: cache saturation",
    "timestamp": "2026-03-04T18:42:00Z",
    "category": "TECHNICAL",
    "source": "custom",
    "environment": "prod",
    "service": "cache",
    "labels": ["incident", "cache"],
    "metadata": {
        "pagerduty_id": "P123456",
        "url": "https://status.acme.com/incidents/123"
    },
}

response = requests.post(
    "https://app-api.costory.io/events",
    headers={
        "Authorization": f"Bearer {os.environ['COSTORY_EVENTS_API_KEY']}",
        "Content-Type": "application/json",
    },
    json=payload,
    timeout=10,
)

response.raise_for_status()
```

<Note>
  For the latest auth headers and endpoint versions, see the [Events API docs](https://app-api.costory.io/docs).
</Note>


# Connect GitHub Events
Source: https://docs.costory.io/setup/events/github

Use the GitHub integration to capture deploys, PR merges, and releases as event markers in Costory.

Use the GitHub integration to capture deploys, PR merges, and releases.

<Steps>
  <Step title="Open Events setup">
    In Costory, go to <strong>Setup -> Events</strong>.
  </Step>

  <Step title="Connect GitHub">
    Click <strong>Connect GitHub</strong> to start the OAuth flow, then authorize the Costory GitHub App for the organization or repositories you want to track.
  </Step>

  <Step title="Approve permissions">
    Costory requests read-only access to repository metadata, pull requests, deployments, and releases. Webhooks are used to deliver events in near real time.
  </Step>
</Steps>

<Note>
  If your organization uses GitHub Enterprise, confirm that outbound webhooks can reach Costory and that the GitHub App is allowed by your org policy.
</Note>


# Provider Events
Source: https://docs.costory.io/setup/events/provider

Automatically track AWS Savings Plans, Reserved Instances, marketplace renewals, and SKU price changes in Costory.

Provider events are generated automatically once your cloud billing data is connected. Costory currently supports AWS provider events.

<CardGroup>
  <Card title="Commitment lifecycle" icon="receipt">
    Track <Tooltip href="/docs/glossary#savings-plans">Savings Plans</Tooltip> and <Tooltip href="/docs/glossary#reserved-instances">Reserved Instances (RIs)</Tooltip> purchases and expirations.
  </Card>

  <Card title="Marketplace renewals" icon="rotate">
    See when third-party subscriptions renew or change.
  </Card>

  <Card title="SKU price changes" icon="tag">
    Track cloud provider pricing updates over time.
  </Card>
</CardGroup>


# Correlate your costs with technical or business metrics
Source: https://docs.costory.io/setup/usage-metrics

Connect external metrics in Costory Integrations, then query usage metrics next to cloud cost in Advanced Explorer.

Billing explains what you spent. External metrics explain why. Connect a usage source in **Integrations**, then query it next to cloud cost in **Advanced Explorer**.

Use this when you need to:

* Reallocate shared infrastructure with a technical signal (requests, latency, schema size)
* Track <Tooltip href="/docs/glossary#unit-economics">unit economics</Tooltip> such as cost per active user or cost per transaction
* Overlay business activity (orders, sessions, pipeline runs) on the same chart as spend

<Frame>
  <img alt="Add integration page showing the External metric section with AWS, GCP, Datadog, Amplitude, Tsuga, and Google Sheets" />
</Frame>

## Add an external metric

<Steps>
  <Step title="Open Add integration">
    Go to [Integrations](https://app.costory.io/integration) and click **+ Add integration**.&#x20;
  </Step>

  <Step title="Pick an External metric tile">
    The page title is **Add integration**. The subtitle is **Choose a provider to connect billing or external metrics.** Tiles are split into **Billing** and **External metric**.
  </Step>

  <Step title="Validate, then save">
    Connect screens are two columns: instructions on the left, **Connection details** on the right. Click **Validate**. **Save connection** stays disabled until validation succeeds. [Custom metrics](/setup/usage-metrics/custom-metrics-push) has no Validate step: **Save connection** creates the table.
  </Step>
</Steps>

After you save, the source appears under **Integrations** > **Data sources**. Most external metric sources use the **External metrics** badge. [Google Sheets](/setup/usage-metrics/google-sheet) uses the **Metrics** badge. [Custom metrics](/setup/usage-metrics/custom-metrics-push) uses the **Custom metrics** badge. A Datadog connection shows **metrics** and, if you enabled CI Visibility, **metrics\_ci**.

<Frame>
  <img alt="Integrations Data sources list showing Docs Datadog, Tsuga, BigQuery, a Google Sheet, and billing datasources" />
</Frame>

<Note>
  Query external metrics in **Advanced Explorer** only. Open **Explore your data**, then switch **Classic** to **Advanced**. Classic greys out non-cost metrics.
</Note>

## External metric providers

<CardGroup>
  <Card title="AWS CloudWatch" icon="chart-line" href="/setup/usage-metrics/aws-cloudwatch">
    CloudWatch metrics. Sub-choice on the AWS tile.
  </Card>

  <Card title="GCP Cloud Monitoring" icon="chart-line" href="/setup/usage-metrics/gcp-cloud-monitoring">
    Live GCP metrics. Sub-choice on the GCP tile.
  </Card>

  <Card title="S3 metrics" icon="box" href="/setup/usage-metrics/s3-parquet">
    Parquet files from S3. Sub-choice on the AWS tile.
  </Card>

  <Card title="BigQuery" icon="database" href="/setup/usage-metrics/bigquery">
    Any BigQuery table, queried live.
  </Card>

  <Card title="Datadog" icon="dog" href="/setup/usage-metrics/datadog">
    Standard metrics. Same connect page as billing.
  </Card>

  <Card title="Datadog CI Visibility" icon="code-branch" href="/setup/usage-metrics/datadog-ci">
    CI and pipeline visibility. Same Datadog connect page.
  </Card>

  <Card title="Amplitude" icon="chart-simple" href="/setup/usage-metrics/amplitude">
    Active users, new users, WAU, and MAU, queried live.
  </Card>

  <Card title="Tsuga" icon="chart-mixed" href="/setup/usage-metrics/tsuga">
    Live cluster metrics, logs, and traces.
  </Card>

  <Card title="Google Sheets" icon="table" href="/setup/usage-metrics/google-sheet">
    Numeric columns from a spreadsheet.
  </Card>

  <Card title="Snowflake" icon="database" href="/setup/usage-metrics/snowflake">
    Tables from a database on your existing Snowflake integration.
  </Card>

  <Card title="Custom metrics" icon="plug" href="/setup/usage-metrics/custom-metrics-push">
    Hourly points you POST with an organization API key.
  </Card>
</CardGroup>

GCS Inventory is not on the **External metric** grid. See [GCS Inventory](/setup/usage-metrics/gcs-inventory) for what to use instead.

## Query after you connect

<Steps>
  <Step title="Open Advanced Explorer">
    Click **Explore your data** in the sidebar, then switch **Classic** to **Advanced**.
  </Step>

  <Step title="Add a metric">
    Click **+ Add Metric**. In the metric picker, use the chips **cost**, **usage**, **metric**, **budget**, and **integrations**.

    <Frame>
      <img alt="Advanced Explorer metric picker open on Cost, with integrations listing Tsuga and BigQuery" />
    </Frame>
  </Step>

  <Step title="Pick the integration">
    Open **integrations**, then choose the source you connected. Helper text describes it as a live external usage metric.
  </Step>

  <Step title="Configure the series">
    For BigQuery, choose a **table**, then set **Date field**, **Value column**, **Aggregate** (for example **SUM**), **Gap fill** (**FORWARD FILL**, **ZERO**, or **LINEAR**), and optional **Group by**.

    <Frame>
      <img alt="Select metric dropdown listing BigQuery tables such as demo_raw.artifact_registry and demo_raw.aws_ec2" />
    </Frame>
  </Step>

  <Step title="Fix an empty chart">
    If the chart is empty, pick a different table and change **Period**. Options include Custom dates, Trailing 7 / 30 / 45 / 90 Days, MTD, QTD, YTD, Last Week, Last Month, Last 3 / 6 / 12 months, and Last Invoice Month.

    <Frame>
      <img alt="Advanced Explorer Period menu listing Custom dates, trailing ranges, MTD, QTD, YTD, and Last Invoice Month" />
    </Frame>

    In the demo workspace, `demo_raw.artifact_*` tables stayed empty at every range. `demo_raw.raw_v2` with **Trailing 90 Days** rendered using date `billing_period_end`, value `billed_cost`, **SUM**, and **FORWARD FILL**.

    <Frame>
      <img alt="Advanced Explorer bar chart of Externalmetric from BigQuery demo_raw.raw_v2 over Trailing 90 Days" />
    </Frame>
  </Step>

  <Step title="Add cost or a formula">
    Optionally click **+ Add Metric** for **Cost**, then **+ Add Formula** such as `b / a`.
  </Step>
</Steps>

See [BigQuery](/setup/usage-metrics/bigquery) for the live table picker and a worked query. See [Unit Economics](/features/unit-economics) for formula patterns, or [cost per active user](/use-cases/amplitude/cost_per_active_users) and [shared Cloud SQL allocation](/use-cases/allocate_shared_cloud_sql_database/allocate) for end-to-end examples.

## Related pages

<CardGroup>
  <Card title="Unit Economics" icon="calculator" href="/features/unit-economics">
    Combine cost with external metrics in Explorer formulas.
  </Card>

  <Card title="Shared Cost Allocation" icon="chart-pie" href="/features/tagging/shared-cost-allocation">
    Split shared infrastructure using a usage metric.
  </Card>

  <Card title="Explorer" icon="magnifying-glass" href="/features/cost-explorer">
    Query cost, usage, and formulas in one chart.
  </Card>

  <Card title="Billing Data" icon="database" href="/setup/billing">
    Connect AWS, GCP, Azure, and SaaS invoices first.
  </Card>
</CardGroup>


# Amplitude
Source: https://docs.costory.io/setup/usage-metrics/amplitude

Query Amplitude active users, new users, WAU, and MAU live in Costory Advanced Explorer. No time series is synced to BigQuery.

Bring product analytics from Amplitude into Costory as external metrics. The **Amplitude** tile covers **Active users**, **New users**, **Weekly active users**, and **Monthly active users**. Queries run live. Costory does not sync a time series to BigQuery.

Use this with [cost per active user](/use-cases/amplitude/cost_per_active_users) when you want spend next to DAU or MAU.

<Frame>
  <img alt="Connect Amplitude live metrics page with API Key, Secret Key, and data region" />
</Frame>

<Tabs>
  <Tab title="Manual setup">
    <Steps>
      <Step title="Copy Amplitude keys">
        In Amplitude, go to **Settings** > **Projects** > **General**. Copy the **API Key** and **Secret Key**, and note the region.
      </Step>

      <Step title="Open the Amplitude tile">
        Go to [Integrations](https://app.costory.io/integration), click **+ Add integration**, then under **External metric** choose **Amplitude**. The connect URL is `/integration/new/amplitude/live-metrics`.&#x20;
      </Step>

      <Step title="Enter connection details">
        Fill **Connection name**, paste the **API Key** and **Secret Key**, and select **Data region** (**US (Standard Server)** or EU residency). Click **Validate**, then **Save connection**.
      </Step>

      <Step title="Query in Advanced Explorer">
        Click **Explore your data**, switch to **Advanced**, then **+ Add Metric**. Open **integrations** and pick Amplitude. See [Query after you connect](/setup/usage-metrics#query-after-you-connect).
      </Step>
    </Steps>

    <Note>
      Queries run live. Costory does not copy Amplitude time series into BigQuery.
    </Note>

    Amplitude API docs: [Dashboard REST API](https://amplitude.com/docs/apis/analytics/dashboard-rest).
  </Tab>

  <Tab title="Terraform">
    Not supported.
  </Tab>
</Tabs>

## Related pages

<CardGroup>
  <Card title="Cost per active user" icon="users" href="/use-cases/amplitude/cost_per_active_users">
    Overlay production cost with Amplitude active users.
  </Card>

  <Card title="Unit Economics" icon="calculator" href="/features/unit-economics">
    Build cost-per-user formulas in Explorer.
  </Card>

  <Card title="Metrics Correlation" icon="chart-line" href="/setup/usage-metrics">
    All external metric sources and the query path.
  </Card>
</CardGroup>


# AWS CloudWatch
Source: https://docs.costory.io/setup/usage-metrics/aws-cloudwatch

Connect AWS CloudWatch as an external metric in Costory. Attach a CloudWatch read policy and trust policy, then query metrics in Advanced Explorer.

Connect AWS CloudWatch to query custom usage metrics, such as S3 storage size, request counts, CPU usage, or queue depth. Costory pairs these with billing data so you can build unit economics.

On **Add integration**, the **AWS** tile is **CloudWatch metrics / Parquet files from S3**. Choose **CloudWatch** on that tile. For Parquet files, see [S3 metrics](/setup/usage-metrics/s3-parquet).

<Frame>
  <img alt="Add integration AWS choice between CloudWatch and S3 metrics" />
</Frame>

<Frame>
  <img alt="Connect AWS CloudWatch form with IAM policy JSON, Role ARN, and AWS region" />
</Frame>

<Frame>
  <img alt="Lower half of Connect AWS CloudWatch with the custom trust policy, Role ARN, region, Validate, and Save connection" />
</Frame>

<Tabs>
  <Tab title="Manual setup">
    <Steps>
      <Step title="Create the CloudWatch read policy">
        In IAM, create a customer managed policy from this JSON. Attach it to the role after you set up trust.

        ```json theme={null}
        {
          "Version": "2012-10-17",
          "Statement": [
            {
              "Sid": "CloudWatchReadForCostory",
              "Effect": "Allow",
              "Action": [
                "cloudwatch:ListMetrics",
                "cloudwatch:GetMetricData",
                "cloudwatch:GetMetricStatistics"
              ],
              "Resource": "*"
            }
          ]
        }
        ```
      </Step>

      <Step title="Create the trust policy">
        Create or edit an IAM role Costory can assume. Use the same web identity trust as [AWS billing](/setup/billing/aws): federated access for Costory's GCP service account. Copy the trust policy from the Costory connect screen, then attach the CloudWatch read policy to that role.
      </Step>

      <Step title="Open the AWS tile">
        Go to [Integrations](https://app.costory.io/integration), click **+ Add integration**, then under **External metric** choose **AWS**. Pick **CloudWatch** (not S3 metrics).&#x20;
      </Step>

      <Step title="Enter connection details">
        Fill **Connection name**, **Role ARN**, and **AWS region**. Click **Validate**, then **Save connection**.
      </Step>

      <Step title="Query in Advanced Explorer">
        Click **Explore your data**, switch to **Advanced**, then **+ Add Metric**. Open **integrations** and pick the CloudWatch source. See [Query after you connect](/setup/usage-metrics#query-after-you-connect).
      </Step>
    </Steps>

    <Note>
      **Save connection** stays disabled until validation succeeds.
    </Note>

    ## Example CloudWatch metrics

    After you connect, pick a CloudWatch metric in Advanced Explorer. One common series is total bytes per S3 bucket (`AWS/S3` `BucketSizeBytes`).

    ```
    SELECT SUM(BucketSizeBytes) FROM SCHEMA("AWS/S3", BucketName,StorageType) GROUP BY BucketName
    ```

    <Frame>
      <img alt="CloudWatch query selecting SUM of BucketSizeBytes grouped by BucketName" />
    </Frame>

    Other series teams query:

    * Total bytes per S3 bucket (`AWS/S3` `BucketSizeBytes`)
    * Request counts on API Gateway, ALB, or CloudFront (`AWS/ApiGateway`, `AWS/ApplicationELB`, `AWS/CloudFront`)
    * Average CPU or memory by service, cluster, or Auto Scaling group (`AWS/EC2`, `AWS/ECS`, `AWS/EKS`)
    * SQS queue length and messages sent or received (`AWS/SQS`)
    * RDS or Aurora connections, CPU, and IOPS (`AWS/RDS`)

    <Frame>
      <img alt="CloudWatch usage metric visualized in Costory" />
    </Frame>
  </Tab>

  <Tab title="Terraform">
    Not supported.
  </Tab>
</Tabs>

## Related pages

<CardGroup>
  <Card title="S3 metrics" icon="box" href="/setup/usage-metrics/s3-parquet">
    Connect Parquet files from S3 on the same AWS tile.
  </Card>

  <Card title="Metrics Correlation" icon="chart-line" href="/setup/usage-metrics">
    Query external metrics in Advanced Explorer.
  </Card>

  <Card title="Unit Economics" icon="calculator" href="/features/unit-economics">
    Divide cloud cost by a CloudWatch metric.
  </Card>

  <Card title="AWS Billing" icon="database" href="/setup/billing/aws">
    Connect CUR 2.0 with the same federated IAM trust.
  </Card>
</CardGroup>


# BigQuery
Source: https://docs.costory.io/setup/usage-metrics/bigquery

Query BigQuery tables live as external metrics in Costory Advanced Explorer. Grant dataset access, validate the project, then pick a table.

Query BigQuery tables live as external metrics in [Advanced Explorer](/setup/usage-metrics#query-after-you-connect). Grant dataset-level access to the Costory service account, validate the project, then pick a table, date field, and value column. Costory does not copy table data.

On **Add integration**, the **GCP** tile lists **Any BigQuery table** and **Cloud Monitoring metrics**. This page is **BigQuery Metric**. For live GCP infrastructure metrics, see [GCP Cloud Monitoring](/setup/usage-metrics/gcp-cloud-monitoring).

<Frame>
  <iframe title="BigQuery external metrics and Costory integration demo" />
</Frame>

<Frame>
  <img alt="Connect GCP BigQuery page with dataset access steps and project ID field" />
</Frame>

<Tabs>
  <Tab title="Manual setup">
    <Steps>
      <Step title="Open the GCP tile">
        Go to [Integrations](https://app.costory.io/integration), click **+ Add integration**, then under **External metric** choose **GCP**. The connect URL is `/integration/new/gcp/bigquery`.&#x20;
      </Step>

      <Step title="Grant dataset access">
        Copy the Costory service account from the connect screen. Open the BigQuery dataset you want Costory to read, share it with that account, and grant **BigQuery Data Viewer** and **BigQuery Metadata Viewer** on the whole dataset, not on individual tables. Project-level access is not required.

        These are the same roles used for [GCP billing export](/setup/billing/gcp).
      </Step>

      <Step title="Enter connection details">
        Set **Connection name** and **GCP project ID**. Click **Validate**, then **Save connection**.
      </Step>
    </Steps>

    <Note>
      This connector queries usage metrics from your BigQuery tables. To import GCP billing data, use [GCP Billing Setup](/setup/billing/gcp). To export Costory dashboard data to your own BigQuery project, see [BigQuery Data Exports](/setup/destinations/bigquery).
    </Note>

    <Tip>
      An EU organization can use a US dataset if it has an EU replica. Analytics Hub linked datasets in the project are included. Share the linked dataset, not the publisher dataset.
    </Tip>

    ## Example table schema

    Your table needs a date column and at least one numeric metric column. Optional string columns work as group-by dimensions.

    ```sql theme={null}
    CREATE TABLE `my-project.analytics.daily_active_users` (
      usage_date DATE,
      product STRING,
      active_users INT64
    );
    ```

    Common metrics to query:

    * Product analytics: daily or monthly active users, sessions, sign-ups
    * Business KPIs: revenue, orders, customers, emails sent
    * Application usage: API calls, background jobs, feature usage counts
    * Data platform activity: query counts, bytes processed, or slot hours per team or project

    ## Table requirements

    | Requirement        | Details                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
    | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | **Region**         | Tables must be in the same region as your Costory workspace. Costory uses **EU** by default and **US** for US-based organizations. Multi-region locations (`EU`, `US`) work. Single-region datasets are not supported because BigQuery can only query tables in the exact same location. Replicate data to `EU` or `US` with [BigQuery data replication](https://cloud.google.com/bigquery/docs/data-replication) if needed. An EU organization can use a US dataset if it has an EU replica. |
    | **Numeric column** | At least one numeric column, such as `FLOAT64`, `NUMERIC`, or `BIGNUMERIC`.                                                                                                                                                                                                                                                                                                                                                                                                                   |
    | **Date column**    | At least one date or timestamp column: `DATE`, `DATETIME`, or `TIMESTAMP`.                                                                                                                                                                                                                                                                                                                                                                                                                    |

    ## Query after you connect

    Queries run live. Costory does not copy table data.

    <Steps>
      <Step title="Open Advanced Explorer">
        Click **Explore your data**, then switch **Classic** to **Advanced**. Classic greys out non-cost metrics.
      </Step>

      <Step title="Add the BigQuery metric">
        Click **+ Add Metric**. Use the **integrations** chip, then pick **BigQuery**. Helper text describes it as a live external usage metric.

        <Frame>
          <img alt="Advanced Explorer metric picker open on Cost, with integrations listing Tsuga and BigQuery" />
        </Frame>
      </Step>

      <Step title="Choose a table and columns">
        Pick a **table** from the picker, then set **Date field**, **Value column**, **Aggregate** (**SUM**), **Gap fill** (**FORWARD FILL**, **ZERO**, or **LINEAR**), and optional **Group by**.

        <Frame>
          <img alt="Select metric dropdown listing BigQuery tables such as demo_raw.artifact_registry and demo_raw.aws_ec2" />
        </Frame>
      </Step>

      <Step title="Fix an empty chart">
        If the chart is empty, pick a different table and change **Period**. Options include Custom dates, Trailing 7 / 30 / 45 / 90 Days, MTD, QTD, YTD, Last Week, Last Month, Last 3 / 6 / 12 months, and Last Invoice Month.

        <Frame>
          <img alt="Advanced Explorer Period menu listing Custom dates, trailing ranges, MTD, QTD, YTD, and Last Invoice Month" />
        </Frame>

        In the demo workspace, `demo_raw.artifact_*` tables stayed empty at every range. `demo_raw.raw_v2` with **Trailing 90 Days** rendered using date `billing_period_end`, value `billed_cost`, **SUM**, and **FORWARD FILL**.

        <Frame>
          <img alt="Advanced Explorer bar chart of Externalmetric from BigQuery demo_raw.raw_v2 over Trailing 90 Days" />
        </Frame>
      </Step>

      <Step title="Add cost or a formula">
        Optionally click **+ Add Metric** for **Cost**, then **+ Add Formula** such as `b / a`.
      </Step>
    </Steps>

    ## Metric configuration

    | Field            | Description                                                                                |
    | ---------------- | ------------------------------------------------------------------------------------------ |
    | **Table**        | The BigQuery table to read.                                                                |
    | **Date field**   | Column used for the time series.                                                           |
    | **Value column** | Column with the metric value.                                                              |
    | **Aggregate**    | How values are rolled up. Use **SUM** unless you have a reason to pick another aggregate.  |
    | **Gap fill**     | How missing dates are filled: **FORWARD FILL**, **ZERO**, or **LINEAR**.                   |
    | **Group by**     | Optional dimension column to split the metric (for example team, product, or environment). |

    Use the series in a [<Tooltip href="/docs/glossary#virtual-dimensions">virtual dimension</Tooltip>](/features/tagging/dimensions#virtual-dimensions) or [shared cost allocation](/features/tagging/shared-cost-allocation) rule after you can query it in Explorer.

    See [Unit Economics](/features/unit-economics) for formula examples, or [BigQuery cost visibility with dbt](/use-cases/dbt_bigquery_visibility/increase_visibility) for attributing warehouse spend by model or team.

    ## Troubleshooting

    | Issue                                   | What to check                                                                                                                                                                                                                                                                                          |
    | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
    | **Table does not appear**               | Confirm the dataset is shared with the Costory service account on the whole dataset, the table has both a date and numeric column, and the dataset region matches your Costory workspace (or has an EU replica for an EU org). For Analytics Hub, share the linked dataset, not the publisher dataset. |
    | **Chart is empty**                      | Pick a different table and change **Period**. In the demo workspace, `demo_raw.artifact_*` stayed empty. `demo_raw.raw_v2` with **Trailing 90 Days** rendered.                                                                                                                                         |
    | **Wrong date or value column selected** | Open the metric configuration and pick the correct columns.                                                                                                                                                                                                                                            |
    | **Dataset is in a single region**       | Replicate the dataset to `EU` or `US` with [BigQuery data replication](https://cloud.google.com/bigquery/docs/data-replication).                                                                                                                                                                       |
  </Tab>

  <Tab title="Terraform">
    Not supported.
  </Tab>
</Tabs>

## Related pages

<CardGroup>
  <Card title="GCP Cloud Monitoring" icon="chart-line" href="/setup/usage-metrics/gcp-cloud-monitoring">
    Query live GCP metrics on the same GCP tile.
  </Card>

  <Card title="Unit Economics" icon="chart-line" href="/features/unit-economics">
    Combine BigQuery metrics with cloud cost in Explorer formulas.
  </Card>

  <Card title="Shared Cost Allocation" icon="chart-pie" href="/features/tagging/shared-cost-allocation">
    Split shared infrastructure costs using BigQuery usage metrics.
  </Card>

  <Card title="Metrics Correlation" icon="database" href="/setup/usage-metrics">
    Browse all supported external metric sources.
  </Card>

  <Card title="BigQuery and dbt visibility" icon="magnifying-glass-chart" href="/use-cases/dbt_bigquery_visibility/increase_visibility">
    Attribute BigQuery spend by dbt model, package, or team.
  </Card>
</CardGroup>


# Custom Metrics Push
Source: https://docs.costory.io/setup/usage-metrics/custom-metrics-push

Push hourly custom metrics to Costory over HTTP with an organization API key, then query them in Advanced Explorer, MCP, and virtual dimensions.

Push your own hourly metrics when the signal lives in a cron job, a sidecar, or a warehouse Costory cannot query live. Create a **Custom metrics** integration, POST points with an organization API key, then use them in [Advanced Explorer](/setup/usage-metrics#query-after-you-connect) like any other external metric.

Use this when you need to:

* Overlay a business counter (orders, jobs, active tenants) that only your app computes, then chart <Tooltip href="/docs/glossary#unit-economics">unit economics</Tooltip> such as cost per order
* Drive [shared cost allocation](/features/tagging/shared-cost-allocation) from a usage key you already emit
* Backfill historical hourly points onto the same path your hourly job uses

<Frame>
  <img alt="Add integration page showing the External metric section with AWS, GCP, Datadog, Amplitude, Tsuga, and Google Sheets" />
</Frame>

<Check>
  Before you begin, make sure you have:

  * Admin access in Costory (creating the integration is admin-only)
  * An **organization** API key (`ak_*`) from [API Keys](/get-started/settings). User keys and browser sessions return 401 on ingest
  * Metrics already aggregated to the hour. Costory truncates every timestamp to the hour in UTC
</Check>

<Tabs>
  <Tab title="Manual setup">
    <Steps>
      <Step title="Create an organization API key">
        Open **API Keys** from the menu next to your name. Create an **organization** token (admins only). Store it as `COSTORY_ORG_API_KEY`. User-scoped tokens and session cookies cannot ingest points. See [API overview](/api-reference/overview).
      </Step>

      <Step title="Open Custom metrics">
        Go to [Integrations](https://app.costory.io/integration), click **+ Add integration**, then under **External metric** choose **Custom metrics**. The tile is **Hourly points you push over HTTP**. The connect URL is `/integration/new/custom-metrics/push`.&#x20;
      </Step>

      <Step title="Name the connection">
        Set **Connection name** (default **Custom metrics**), then click **Save connection**. There is no **Validate** step. Costory creates an empty table for this integration. No vendor credentials.
      </Step>

      <Step title="Copy the ingest details">
        After save, Costory shows **Custom metrics is ready**, the **Integration id**, and a curl example. Keep the id. You can open **Show details** later from the integration menu.
      </Step>

      <Step title="POST hourly points">
        Send one or more points to `POST /integrations/:id/metrics/points`. Hourly jobs send one point. Backfill sends up to 10,000 on the same path.

        ```bash theme={null}
        curl -X POST "https://app-api.costory.io/integrations/YOUR_INTEGRATION_ID/metrics/points" \
          -H "Authorization: Bearer $COSTORY_ORG_API_KEY" \
          -H "Content-Type: application/json" \
          -d '{"points":[{"metric_name":"orders","ts":"2026-09-02T15:00:00Z","value":42,"tags":{"env":"prod"}}]}'
        ```

        A successful write returns `202` with `inserted` (rows after in-batch dedupe) and `truncatedHours` (distinct hour buckets written).
      </Step>

      <Step title="Refresh the catalog">
        Ingest does not update the metric picker. After the first push, open the integration menu and click **Refresh metrics**. New metric names and tag keys appear in **Advanced Explorer** after that refresh. Metrics that stop reporting stay in the catalog so saved queries keep resolving.
      </Step>

      <Step title="Query in Advanced Explorer">
        Click **Explore your data**, switch to **Advanced**, then **+ Add Metric**. Open **integrations** and pick the **Custom metrics** source. Group by tag keys from the points you pushed. See [Query after you connect](/setup/usage-metrics#query-after-you-connect).
      </Step>
    </Steps>

    ## Point payload

    Each request body is `{ "points": [ ... ] }` with 1 to 10,000 points.

    | Field         | Type                                                     | Rules                                                                                                                                                                                                            |
    | ------------- | -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | `metric_name` | string                                                   | 1 to 255 characters. No control characters. Opaque: Costory does not enforce a Prometheus name charset.                                                                                                          |
    | `ts`          | ISO-8601 datetime with offset, or epoch **milliseconds** | Truncated to the hour in UTC before insert. Unix seconds (a \~1e9 number) are rejected.                                                                                                                          |
    | `value`       | number                                                   | Finite. `NaN` and infinity return 400.                                                                                                                                                                           |
    | `tags`        | object                                                   | Optional. Defaults to `{}`. Keys must be SQL identifiers: start with a letter or `_`, then letters, digits, or `_` (max 128). Values are string, number, or boolean. Nested objects and arrays are not accepted. |

    Tag keys become Explorer group-bys. A key such as `env-name` is rejected because it is not a valid identifier.

    The last write for the same `metric_name`, hour, and tags wins. If one request repeats that key, the last array element is kept. Retrying a failed request can insert duplicates. Query-time last-write-wins hides them.

    ## Python example

    ```python theme={null}
    import os
    import requests

    integration_id = os.environ["COSTORY_CUSTOM_METRICS_ID"]
    payload = {
        "points": [
            {
                "metric_name": "orders",
                "ts": "2026-09-02T15:00:00Z",
                "value": 42,
                "tags": {"env": "prod"},
            }
        ]
    }

    response = requests.post(
        f"https://app-api.costory.io/integrations/{integration_id}/metrics/points",
        headers={
            "Authorization": f"Bearer {os.environ['COSTORY_ORG_API_KEY']}",
            "Content-Type": "application/json",
        },
        json=payload,
        timeout=10,
    )
    response.raise_for_status()
    print(response.json())
    ```

    ## After you save

    On the source row menu you can:

    * **Show details** (integration id and curl again)
    * **Refresh metrics** (catalog only, admin)
    * **Remove Custom metrics integration** (admin). Removal drops the table and catalog rows for that integration.

    You can create more than one Custom metrics integration per organization, for example staging versus production push sources.

    Query the series through [Costory MCP](/features/mcp) as well: `list_metrics` returns the catalog, and `query` accepts `{ type: "externalMetric", integrationId, metricName }`.

    <Note>
      Tag filters (`conditions`) are not available on Custom metrics in this version. Split series with group-by on tag keys instead.
    </Note>
  </Tab>

  <Tab title="Terraform">
    Not supported.
  </Tab>
</Tabs>

## Prometheus

Costory does not speak Prometheus remote-write. Run a sidecar next to Prometheus that maps name, timestamp, labels, and value onto this POST. Preaggregate to the hour before you send. Cron and sidecars must use the organization API key, not a session cookie.

## FAQ

<AccordionGroup>
  <Accordion title="Why do I get 401 when I POST points?">
    The ingest path accepts only a Clerk **organization** API key (`ak_*` with an `org_*` subject). User API keys, session JWTs, and Swagger session auth return 401, even for admins. Create the token under **API Keys** as an organization token. See [API overview](/api-reference/overview).
  </Accordion>

  <Accordion title="I pushed points but Advanced Explorer is empty.">
    Click **Refresh metrics** on the integration menu. The catalog is not updated on ingest. Then pick the **Custom metrics** source under **integrations** and confirm the **Period** covers hours you wrote.
  </Accordion>

  <Accordion title="Can I send second-level timestamps?">
    Yes. Costory truncates them to the hour in UTC. Preaggregate in your job if several samples in the same hour should not collapse to the last write.
  </Accordion>

  <Accordion title="Can I send Unix seconds?">
    No. A numeric `ts` must be epoch milliseconds (12+ digits after 2001). Seconds look like `1750000000` and are rejected so they are not stored as 1970.
  </Accordion>

  <Accordion title="What happens if I push the same hour twice?">
    The later `inserted_at` wins for that metric name, hour, and tags. Explorer shows the last value.
  </Accordion>

  <Accordion title="Does Costory pull from my Prometheus or warehouse?">
    No. This connector only accepts HTTP POST. If the data already lives in BigQuery or Snowflake, use [BigQuery](/setup/usage-metrics/bigquery) or [Snowflake Metrics](/setup/usage-metrics/snowflake) instead.
  </Accordion>
</AccordionGroup>

## Related pages

<CardGroup>
  <Card title="Metrics Correlation" icon="chart-line" href="/setup/usage-metrics">
    All external metric sources and the Explorer query path.
  </Card>

  <Card title="Unit Economics" icon="calculator" href="/features/unit-economics">
    Divide cloud cost by a metric you push.
  </Card>

  <Card title="Shared Cost Allocation" icon="chart-pie" href="/features/tagging/shared-cost-allocation">
    Split shared costs with a usage metric.
  </Card>

  <Card title="API overview" icon="key" href="/api-reference/overview">
    Create an organization API key for ingest.
  </Card>
</CardGroup>


# Datadog
Source: https://docs.costory.io/setup/usage-metrics/datadog

Connect Datadog in Costory Integrations for billing, standard metrics, and CI visibility. Query standard metrics with rollups in Advanced Explorer.

Connect Datadog from **Add integration** for billing, standard metrics, and CI visibility. Pick at least one use-case card, then validate the keys.

This page covers **Standard metrics**. For Datadog spend in Explorer, see [Datadog Billing](/setup/billing/datadog). For pipeline metrics, see [Datadog CI Visibility](/setup/usage-metrics/datadog-ci).

<Frame>
  <img alt="Connect Datadog page with Billing, Standard metrics, and connection fields" />
</Frame>

<Tabs>
  <Tab title="Manual setup">
    <Steps>
      <Step title="Open the Datadog tile">
        Go to [Integrations](https://app.costory.io/integration), click **+ Add integration**, then under **External metric** choose **Datadog**. The tile reads **Standard metrics / CI Visibility**. The connect URL is `/integration/new/datadog/connect`.&#x20;
      </Step>

      <Step title="Pick at least one use case">
        On **What should Costory use Datadog for?**, pick at least one card:

        * **Billing / spend in Costory**: see Datadog billing data in Costory. Setup details live on [Datadog Billing](/setup/billing/datadog).
        * **Standard metrics**: use Datadog metrics in Costory to calculate marginal costs and correlate usage with spend.
        * **CI / pipeline visibility**: pull CI Visibility aggregations. See [Datadog CI Visibility](/setup/usage-metrics/datadog-ci).
      </Step>

      <Step title="Enter connection details">
        Fill **Connection name**, **Datadog site / region** (for example `datadoghq.com` or `datadoghq.eu`), **API Key**, and **Application Key**. Click **Validate**, then **Save connection**.

        <Frame>
          <img alt="Connect Datadog with Standard metrics and CI visibility selected, keys filled, and Ready to save" />
        </Frame>
      </Step>

      <Step title="Query a metric with a rollup">
        In **Advanced Explorer**, click **+ Add Metric**, open **integrations**, and pick Datadog. Search a metric name, then pick it from the list. Provide a query **with a rollup**, for example:

        `avg:system.cpu.user{*} by {host}.rollup(avg, daily, 'UTC')`

        Use **Edit DataDog query** on the series row if you need to change the query string. See [Query after you connect](/setup/usage-metrics#query-after-you-connect).

        <Frame>
          <img alt="Advanced Explorer Datadog metric picker listing render.service metrics with group-by tags" />
        </Frame>

        <Frame>
          <img alt="Advanced Explorer bar chart of Cost grouped by service next to a Datadog HTTP requests metric" />
        </Frame>
      </Step>
    </Steps>

    <Note>
      One Datadog connection can cover billing and metrics. Billing creates cost rows. Standard metrics and CI Visibility are external metrics, queried in **Advanced Explorer**. Classic greys out non-cost metrics. Costory validates each selected scope when you click **Validate**. A key can have `metrics_read` and `timeseries_query` while billing data remains unavailable.
    </Note>

    ## API reference

    Costory queries Datadog metrics through the [Metrics API](https://docs.datadoghq.com/api/latest/metrics/):

    | Use case         | Endpoint                                                                                                               | Required scopes                    |
    | ---------------- | ---------------------------------------------------------------------------------------------------------------------- | ---------------------------------- |
    | Standard metrics | `POST /api/v2/query/timeseries`                                                                                        | `metrics_read`, `timeseries_query` |
    | CI visibility    | [Aggregate pipeline events](https://docs.datadoghq.com/api/latest/ci-visibility-pipelines/#aggregate-pipelines-events) | `ci_visibility_read`               |

    The base URL depends on your Datadog site (for example `https://api.datadoghq.com` for US1). Costory sends your API key and application key on every request. Enable the matching capabilities under **Organization Settings** > **Application Keys**. Costory validates each selected scope when you click **Validate**.

    See [Query timeseries points](https://docs.datadoghq.com/api/latest/metrics/#query-timeseries-points) for request body fields and response format.
  </Tab>

  <Tab title="Terraform">
    Not supported.
  </Tab>
</Tabs>

## Related pages

<CardGroup>
  <Card title="Datadog Billing" icon="file-invoice-dollar" href="/setup/billing/datadog">
    Pull Datadog usage and billing estimates as cost rows.
  </Card>

  <Card title="Datadog CI Visibility" icon="code-branch" href="/setup/usage-metrics/datadog-ci">
    Connect the same page and pick the CI Visibility card.
  </Card>

  <Card title="Metrics Correlation" icon="chart-line" href="/setup/usage-metrics">
    Query external metrics in Advanced Explorer.
  </Card>

  <Card title="Unit Economics" icon="calculator" href="/features/unit-economics">
    Divide cloud cost by a Datadog metric.
  </Card>
</CardGroup>


# Datadog CI Visibility
Source: https://docs.costory.io/setup/usage-metrics/datadog-ci

Connect Datadog CI Visibility from the same Costory Integrations page as Datadog billing and standard metrics.

Pull CI and pipeline visibility metrics from Datadog into Costory. You use the same **Connect Datadog** page as [standard metrics](/setup/usage-metrics/datadog). Pick the **CI / pipeline visibility** card, validate the keys, then query in [Advanced Explorer](/setup/usage-metrics#query-after-you-connect).

<Frame>
  <img alt="Connect Datadog page with Standard metrics and CI / pipeline visibility selected, ready to save" />
</Frame>

<Tabs>
  <Tab title="Manual setup">
    <Steps>
      <Step title="Open Connect Datadog">
        Go to [Integrations](https://app.costory.io/integration), click **+ Add integration**, then under **External metric** choose **Datadog**. The tile reads **Standard metrics / CI Visibility**. The connect URL is `/integration/new/datadog/connect`.&#x20;
      </Step>

      <Step title="Pick CI / pipeline visibility">
        On **What should Costory use Datadog for?**, pick **CI / pipeline visibility**. You can also select **Standard metrics** or **Billing / spend in Costory** on the same connection.
      </Step>

      <Step title="Enter connection details">
        Fill **Connection name**, **Datadog site / region** (for example `datadoghq.com` or `datadoghq.eu`), **API Key**, and **Application Key**. The CI card requires the `ci_visibility_read` scope on the application key. Click **Validate**, then **Save connection**.
      </Step>

      <Step title="Query in Advanced Explorer">
        Click **Explore your data**, switch to **Advanced**, then **+ Add Metric**. Open **integrations** and pick Datadog. Provide the CI Visibility query, aggregation, and optional group-by fields.

        <Frame>
          <img alt="Advanced Explorer Datadog metric picker listing render.service metrics with group-by tags" />
        </Frame>
      </Step>
    </Steps>

    API reference: [Aggregate pipeline events](https://docs.datadoghq.com/api/latest/ci-visibility-pipelines/#aggregate-pipelines-events).

    <Note>
      Billing and CI visibility are different use cases on the same connect page. Billing creates cost rows. CI Visibility is an external metric. See [Datadog Billing](/setup/billing/datadog) if you also want spend.
    </Note>
  </Tab>

  <Tab title="Terraform">
    Not supported.
  </Tab>
</Tabs>

## Related pages

<CardGroup>
  <Card title="Datadog standard metrics" icon="chart-line" href="/setup/usage-metrics/datadog">
    Connect the same page and pick Standard metrics.
  </Card>

  <Card title="Metrics Correlation" icon="database" href="/setup/usage-metrics">
    Query after you connect in Advanced Explorer.
  </Card>
</CardGroup>


# GCP Cloud Monitoring
Source: https://docs.costory.io/setup/usage-metrics/gcp-cloud-monitoring

Connect Google Cloud Monitoring as a live external metric in Costory. Grant Monitoring Viewer, validate a project, then query GCP metrics in Advanced Explorer.

Connect Google Cloud Monitoring when your usage signal already lives in GCP: GKE CPU, Cloud Storage bytes, Cloud SQL connections, Compute Engine utilization, or a custom metric. Costory queries the Monitoring API live and plots those series next to cost in [Advanced Explorer](/setup/usage-metrics#query-after-you-connect). It does not copy metric data.

On **Add integration**, the **GCP** tile lists **Any BigQuery table** and **Cloud Monitoring metrics**. Choose **Cloud Monitoring**. For tables, see [BigQuery](/setup/usage-metrics/bigquery).

<Frame>
  <img alt="Add integration page showing Billing tiles and an External metric section with Datadog, AWS, GCP, Amplitude, Tsuga, and Google Sheets" />
</Frame>

<Tabs>
  <Tab title="Manual setup">
    <Steps>
      <Step title="Open Cloud Monitoring">
        Go to [Integrations](https://app.costory.io/integration), click **+ Add integration**, then under **External metric** choose **GCP**. On **Choose what to connect**, pick **Cloud Monitoring**. The connect URL is `/integration/new/gcp/cloud-monitoring`. You need to be an admin.&#x20;
      </Step>

      <Step title="Grant Monitoring Viewer">
        Copy the **Service account** from the connect screen. Grant project-level **Monitoring Viewer** (`roles/monitoring.viewer`) so Costory can list and query metrics. The role is read-only. It covers every Monitoring series in that project. You cannot scope it to a single metric.

        Run the command shown under **gcloud**, or paste this and replace the placeholders:

        ```bash theme={null}
        gcloud projects add-iam-policy-binding PROJECT_ID \
          --member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
          --role="roles/monitoring.viewer"
        ```

        The **GCP project ID** you enter updates the command on the page.
      </Step>

      <Step title="Enter connection details">
        Set **Connection name** (default **Cloud Monitoring**) and **GCP project ID**. Click **Validate**. Costory lists active metrics in the project's metrics scope and shows a count such as **Found 42 active metrics in this project's metrics scope.** Click **Save connection**.

        **Save connection** stays disabled until validation succeeds.
      </Step>

      <Step title="Query in Advanced Explorer">
        Click **Explore your data**, switch **Classic** to **Advanced**, then **+ Add Metric**. Open **integrations** and pick the Cloud Monitoring source. Search a metric type. The picker shows the path after the service domain, for example `instance/cpu/utilization` for `compute.googleapis.com/instance/cpu/utilization`.

        See [Query after you connect](/setup/usage-metrics#query-after-you-connect).
      </Step>
    </Steps>

    <Note>
      Enable the Cloud Monitoring API (`monitoring.googleapis.com`) on the project before you validate. A disabled API fails with a permission-style error.
    </Note>

    <Tip>
      Grant the role on a [scoping project](https://cloud.google.com/monitoring/settings) if you use a metrics scope. That one grant covers every project in the scope. You can then group by `resource.label.project_id` instead of connecting each project.
    </Tip>

    ## Connection fields

    | Field               | Description                                                                                                       | Default          |
    | ------------------- | ----------------------------------------------------------------------------------------------------------------- | ---------------- |
    | **Connection name** | Label on the Integrations list and in the Explorer picker.                                                        | Cloud Monitoring |
    | **GCP project ID**  | Project Costory calls on the Monitoring API. Use the scoping project if you monitor many projects from one scope. | (empty)          |

    ## What you can query

    After you save, active metrics from the connected project appear under **integrations**. Queries run against Cloud Monitoring. Costory does not store the timeseries.

    <Frame>
      <img alt="Google Cloud Monitoring metrics picker" />
    </Frame>

    Common series:

    * Compute Engine CPU utilization (`compute.googleapis.com/instance/cpu/utilization`)
    * GKE container CPU request utilization (`kubernetes.io/container/cpu/request_utilization`)
    * Cloud Storage object or byte counts (`storage.googleapis.com`)
    * Cloud SQL connections or PostgreSQL insights execution time (`cloudsql.googleapis.com`)
    * Custom or Prometheus metrics you already export to Cloud Monitoring

    Set **Aggregate** to **SUM**, **AVERAGE**, **MAX**, or **MIN**. Optional **Group by** uses Monitoring labels, written as `metric.label.*` or `resource.label.*`. `resource.label.project_id` is always available.

    To narrow the series, paste a Cloud Monitoring filter in the condition field. The field is not validated in the UI. Example:

    ```
    resource.label.cluster_name = "prod-gke"
    ```

    Costory always constrains the query to the metric you picked. Your filter is combined with that metric type.

    Use the series in a [<Tooltip href="/docs/glossary#virtual-dimensions">virtual dimension</Tooltip>](/features/tagging/dimensions#virtual-dimensions) or [shared cost allocation](/features/tagging/shared-cost-allocation) rule after you can query it in Explorer. For formulas such as cost per request, see [Unit Economics](/features/unit-economics).

    ## Limits

    | Topic                   | Details                                                                                                                        |
    | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
    | **Active metrics only** | Validation and the picker list metrics with data in roughly the last 25 hours. A project with no recent points fails validate. |
    | **Numeric metrics**     | `INT64` and `DOUBLE` values work. `DISTRIBUTION`, `BOOL`, `STRING`, and `MONEY` are not supported.                             |
    | **Group-by cap**        | Explorer keeps the 200 largest groups by magnitude.                                                                            |
    | **API billing**         | Listing descriptors is free. Timeseries reads are billed to your GCP billing account.                                          |
    | **No PromQL**           | Pick a metric and optional filter. There is no free-text PromQL or MQL box.                                                    |

    ## Troubleshooting

    | Issue                                   | What to check                                                                                                                           |
    | --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
    | **Permission denied**                   | Grant `roles/monitoring.viewer` to the Costory service account on the same project ID you entered.                                      |
    | **Cloud Monitoring API is not enabled** | Enable `monitoring.googleapis.com` on that project, then validate again.                                                                |
    | **Project not found**                   | Confirm the project ID spelling and that the service account can see the project.                                                       |
    | **No active metrics found**             | The project (or scope) has no metrics with data in about the last 25 hours. Generate traffic or connect a project that already reports. |
    | **Rate limited**                        | Wait a few minutes and retry. Check the project's Monitoring API quota if it keeps failing.                                             |
    | **Chart is empty**                      | Search the full metric type, change **Period**, and confirm the metric still has recent data. Classic greys out non-cost metrics.       |
    | **Metric missing from the picker**      | Type part of the metric type. The first open is a short page of active metrics, not the full Google catalog.                            |
  </Tab>

  <Tab title="Terraform">
    Not supported.
  </Tab>
</Tabs>

## Related pages

<CardGroup>
  <Card title="BigQuery metrics" icon="database" href="/setup/usage-metrics/bigquery">
    Query a table instead of the Monitoring API on the same GCP tile.
  </Card>

  <Card title="Metrics Correlation" icon="chart-line" href="/setup/usage-metrics">
    Query external metrics in Advanced Explorer.
  </Card>

  <Card title="Unit Economics" icon="calculator" href="/features/unit-economics">
    Divide cloud cost by a Cloud Monitoring series.
  </Card>

  <Card title="GCP Billing" icon="file-invoice-dollar" href="/setup/billing/gcp">
    Connect Detailed Usage Cost export for GCP spend.
  </Card>
</CardGroup>


# GCS Inventory (Parquet)
Source: https://docs.costory.io/setup/usage-metrics/gcs-inventory

GCS Inventory is not on the Costory Add integration External metric grid. Query warehouse-native metrics with BigQuery instead.

GCS Inventory writes Parquet files into a GCS bucket. Create a BigQuery external table over those files, then query the table as a live metric.

<Tabs>
  <Tab title="Manual setup">
    1. Load the inventory (or any metric table) into a BigQuery dataset that Costory can read.
    2. Go to [Integrations](https://app.costory.io/integration), click **+ Add integration**, then under **External metric** choose **GCP**.&#x20;
    3. Follow [BigQuery](/setup/usage-metrics/bigquery) to grant **BigQuery Data Viewer** and **BigQuery Metadata Viewer** on the dataset, validate the project, and query the table in **Advanced Explorer**.
  </Tab>

  <Tab title="Terraform">
    Not supported.
  </Tab>
</Tabs>

## Related pages

<CardGroup>
  <Card title="BigQuery" icon="database" href="/setup/usage-metrics/bigquery">
    Query any BigQuery table as a live external metric.
  </Card>

  <Card title="Metrics Correlation" icon="chart-line" href="/setup/usage-metrics">
    All External metric tiles and the Explorer query path.
  </Card>
</CardGroup>


# Google Sheets
Source: https://docs.costory.io/setup/usage-metrics/google-sheet

Connect numeric metrics from a Google spreadsheet in Costory and query them as external metrics in Advanced Explorer.

Connect numeric metrics from a spreadsheet. Costory reads the sheet in place. You map a date column and the metric columns, then query them in [Advanced Explorer](/setup/usage-metrics#query-after-you-connect).

<Frame>
  <img alt="Connect Google Sheets page with sheet-shape instructions and Create a new Google Sheet" />
</Frame>

<Tabs>
  <Tab title="Manual setup">
    <Steps>
      <Step title="Open the Google Sheets tile">
        Go to [Integrations](https://app.costory.io/integration), click **+ Add integration**, then under **External metric** choose **Google Sheets**. The connect URL is `/integration/new/google-sheets/external-metrics`.&#x20;
      </Step>

      <Step title="Shape the sheet">
        The first row is the header. Dates must be `YYYY-MM-DD` or `YYYY/MM/DD`. Metric columns must be numeric.

        | date       | metric1 | metric2 |
        | ---------- | ------- | ------- |
        | 2024-01-01 | 42      | 123     |
      </Step>

      <Step title="Paste the Sheet ID">
        Paste the Sheet ID or the full spreadsheet URL in **Connection details**. Copy the ID from the sheet URL, between `/d/` and the next `/`.
      </Step>

      <Step title="Share the sheet">
        Share the spreadsheet with `importer-sheets@costory.io`. Sheets created in-app are already shared.&#x20;
      </Step>

      <Step title="Create a starter sheet (optional)">
        Click **Create a new Google Sheet** to make a starter sheet with a date column and a sample metric. Costory fills the Sheet ID for you.
      </Step>

      <Step title="Validate, then map columns">
        Click **Validate**. Success looks like: **Validation succeeded. Sheet headers loaded. Matching date and numeric columns were pre-selected.**

        Map **Metrics columns** (columns Costory reads as metrics) and **Date column**. Costory checks that metric columns are **Numeric** and that dates look valid.
      </Step>

      <Step title="Save the connection">
        Click **Save connection**. The source appears under **Integrations** > **Data sources** with the **Metrics** badge.
      </Step>
    </Steps>

    ## After you save

    On the source row menu you can:

    * **View metric**
    * **Rename**
    * **Edit definition**
    * **Create formula**
    * **Delete**

    When you **Edit definition** and add a metric, Costory appends a column to the sheet header.

    Query the series in **Advanced Explorer**. Click **+ Add Metric**, use the **integrations** chip, then pick the Sheets source. See [Query after you connect](/setup/usage-metrics#query-after-you-connect).

    <Frame>
      <img alt="Advanced Explorer metric picker open on Cost, with integrations listing Tsuga and BigQuery" />
    </Frame>

    <Frame>
      <img alt="Advanced Explorer Period menu listing Custom dates, trailing ranges, MTD, QTD, YTD, and Last Invoice Month" />
    </Frame>

    <Note>
      **Save connection** stays disabled until validation succeeds.
    </Note>
  </Tab>

  <Tab title="Terraform">
    Not supported.
  </Tab>
</Tabs>

## Related pages

<CardGroup>
  <Card title="Metrics Correlation" icon="chart-line" href="/setup/usage-metrics">
    All external metric sources and the Explorer query path.
  </Card>

  <Card title="Unit Economics" icon="calculator" href="/features/unit-economics">
    Divide cloud cost by a Sheets metric.
  </Card>

  <Card title="BigQuery" icon="database" href="/setup/usage-metrics/bigquery">
    Query warehouse tables live instead of a spreadsheet.
  </Card>

  <Card title="Shared Cost Allocation" icon="chart-pie" href="/features/tagging/shared-cost-allocation">
    Split shared costs with a usage metric.
  </Card>
</CardGroup>


# S3 metrics
Source: https://docs.costory.io/setup/usage-metrics/s3-parquet

Connect Parquet files from AWS S3 as external metrics in Costory. Scan a bucket prefix, then query discovered metrics in Advanced Explorer.

Connect Parquet files from S3 as external metrics. On **Add integration**, the **AWS** tile is **CloudWatch metrics / Parquet files from S3**. Choose **S3 metrics** on that tile. For CloudWatch, see [AWS CloudWatch](/setup/usage-metrics/aws-cloudwatch).

Costory mirrors Parquet files under a prefix and exposes each as a metric in Advanced Explorer. Files are mirrored to Google Cloud Storage and exposed through BigQuery external tables. You can trigger a sync manually at any time.

Costory scans only the prefix root plus one directory level. A directory of `part-*.parquet` files counts as one metric. Every other `.parquet` file is its own metric, including dated snapshots. Hive partitions (`dt=2026-08-01/`) are not supported. The maximum is 50 metrics per bucket.

<Frame>
  <img alt="Connect an S3 bucket form with scan rules, Role ARN, bucket name, and optional prefix" />
</Frame>

<Frame>
  <img alt="Lower half of Connect an S3 bucket with the S3 read policy, Force validate, Validate, and Save connection" />
</Frame>

<Tabs>
  <Tab title="Manual setup">
    <Steps>
      <Step title="Store Parquet files in S3">
        Put metric files under a bucket prefix. Keep the layout to the prefix root and one directory. Do not rely on Hive-style partitions (`dt=2026-08-01/...`).
      </Step>

      <Step title="Create a read-only IAM role">
        Create an IAM role with read-only S3 access on that bucket and prefix, plus a web identity trust for Costory. Use the same federated trust as [AWS billing](/setup/billing/aws). Copy the trust policy from the Costory connect screen.
      </Step>

      <Step title="Open the AWS tile">
        Go to [Integrations](https://app.costory.io/integration), click **+ Add integration**, then under **External metric** choose **AWS**. Pick **S3 metrics**.&#x20;
      </Step>

      <Step title="Enter connection details">
        Fill **Connection name**, **Role ARN**, and **Bucket name**. **Prefix** is optional. Click **Validate**, then **Save connection**. Use **Force validate** if you need to re-check the role and bucket after a failed attempt.
      </Step>

      <Step title="Query in Advanced Explorer">
        Click **Explore your data**, switch to **Advanced**, then **+ Add Metric**. Open **integrations** and pick the S3 source. See [Query after you connect](/setup/usage-metrics#query-after-you-connect).
      </Step>
    </Steps>

    <Note>
      **Save connection** stays disabled until validation succeeds. Hive partitions are not supported. Costory stops at 50 metrics per bucket.
    </Note>

    ## How files become metrics

    | Layout                                  | Result                                    |
    | --------------------------------------- | ----------------------------------------- |
    | Directory of `part-*.parquet` files     | One metric                                |
    | Any other `.parquet` file               | Its own metric, including dated snapshots |
    | Hive partitions (`dt=…/`)               | Not supported                             |
    | Deeper than prefix root + one directory | Not scanned                               |
  </Tab>

  <Tab title="Terraform">
    ```hcl theme={null}
    terraform {
      required_providers {
        costory = {
          source  = "costory-io/costory"
          version = ">= 0.1.0"
        }
      }
    }

    variable "costory_token" {
      type        = string
      description = "Costory API token."
      sensitive   = true
    }

    variable "s3_bucket_name" {
      type        = string
      description = "S3 bucket containing parquet metrics files."
    }

    variable "s3_prefix" {
      type        = string
      description = "S3 key prefix for parquet files."
      default     = ""
    }

    variable "role_arn" {
      type        = string
      description = "IAM role ARN for Costory to assume (must match arn:aws:iam::)."
    }

    provider "costory" {
      token = var.costory_token
    }

    resource "costory_metrics_datasource_s3_parquet" "main" {
      name        = "AWS S3 Metrics"
      bucket_name = var.s3_bucket_name
      prefix      = var.s3_prefix
      role_arn    = var.role_arn

      metrics_definition {
        metric_name  = "Usage"
        gap_filling  = "ZERO"
        aggregation  = "SUM"
        value_column = "usage_amount"
        date_column  = "usage_start_date"
        dimensions   = ["service", "region"]
        unit         = "count"
      }
    }

    resource "costory_metrics_datasource_s3_parquet" "multiple" {
      name        = "Multiple metrics"
      bucket_name = var.s3_bucket_name
      prefix      = var.s3_prefix
      role_arn    = var.role_arn

      metrics_definition {
        metric_name  = "Nbr of R&D teams"
        gap_filling  = "FORWARD_FILL"
        aggregation  = "SUM"
        value_column = "nbr_rd_teams"
        date_column  = "usage_start_date"
        unit         = "count"
      }
      metrics_definition {
        metric_name  = "Organizations"
        gap_filling  = "FORWARD_FILL"
        aggregation  = "SUM"
        value_column = "nbr_organizations"
        date_column  = "usage_start_date"
        unit         = "count"
      }
    }
    ```
  </Tab>
</Tabs>

## Related pages

<CardGroup>
  <Card title="AWS CloudWatch" icon="chart-line" href="/setup/usage-metrics/aws-cloudwatch">
    Connect CloudWatch on the same AWS tile.
  </Card>

  <Card title="Metrics Correlation" icon="database" href="/setup/usage-metrics">
    Query external metrics in Advanced Explorer.
  </Card>

  <Card title="Google Sheets" icon="table" href="/setup/usage-metrics/google-sheet">
    Connect numeric columns from a spreadsheet instead.
  </Card>
</CardGroup>


# Snowflake Metrics
Source: https://docs.costory.io/setup/usage-metrics/snowflake

Query Snowflake tables as live external metrics in Costory. Reuse the billing integration, grant one database, then pick tables in Advanced Explorer.

Active users, sessions, or warehouse activity often already live in Snowflake, while cloud spend lives in Costory. Grant the existing billing role a metrics database, then query those tables live in [Advanced Explorer](/setup/usage-metrics#query-after-you-connect).

Reuse the Costory Snowflake user and warehouse. Pick a table, date field, and value column. Costory queries through the Snowflake SQL API and does not copy table data.

Use this when the signal already lives in Snowflake:

* Business metrics such as active users, sessions, or devices
* Technical metrics for [shared cost allocation](/features/tagging/shared-cost-allocation), such as query counts or bytes scanned by team

The [Snowflake billing](/setup/billing/snowflake) connection stays on the `SNOWFLAKE` database. Metrics are a second grant on databases you choose.

<Frame>
  <img alt="Advanced Explorer bar chart of ACTIVE_CUSTOMERS from Snowflake table MY_BUSINESS_DB.ANALYTICS.MONTHLY_BUSINESS_METRICS, with METRIC_DATE, SUM, and FORWARD FILL" />
</Frame>

<Tabs>
  <Tab title="Manual setup">
    <Steps>
      <Step title="Connect Snowflake billing first">
        You need an existing Snowflake integration (user, role, and warehouse). If none exists, follow [Snowflake billing setup](/setup/billing/snowflake), then come back here. Costory does not create a second user or warehouse for metrics.
      </Step>

      <Step title="Open Snowflake Metrics">
        Go to [Integrations](https://app.costory.io/integration), click **+ Add integration**, choose **Snowflake**, then **Metrics**. The connect URL is `/integration/new/snowflake/metrics`.&#x20;
      </Step>

      <Step title="Select the existing integration">
        Under **Existing integration**, pick the Snowflake connection already used for billing. **Already visible** lists databases you granted earlier.
      </Step>

      <Step title="Grant database access">
        Enter the **Database** name Costory should catalog (for example `ANALYTICS`). Run the grant SQL Costory shows as **ACCOUNTADMIN**. The default role is **COSTORY** unless your integration uses another role.

        ```sql theme={null}
        GRANT USAGE ON DATABASE ANALYTICS TO ROLE COSTORY;
        GRANT USAGE ON ALL SCHEMAS IN DATABASE ANALYTICS TO ROLE COSTORY;
        GRANT SELECT ON ALL TABLES IN DATABASE ANALYTICS TO ROLE COSTORY;
        GRANT SELECT ON ALL VIEWS IN DATABASE ANALYTICS TO ROLE COSTORY;
        GRANT SELECT ON FUTURE TABLES IN DATABASE ANALYTICS TO ROLE COSTORY;
        GRANT SELECT ON FUTURE VIEWS IN DATABASE ANALYTICS TO ROLE COSTORY;
        ```

        Replace `ANALYTICS` and `COSTORY` with the identifiers on the connect screen if they differ.
      </Step>

      <Step title="Validate, then save">
        Click **Validate**. Costory checks that it can list tables in that database. **Save** stays disabled until validation succeeds. Tables in the database then appear as external metrics.
      </Step>
    </Steps>

    <Note>
      **Save** stays disabled until validation succeeds. You can add more databases later on the same integration. Each grant is additive.
    </Note>

    ## Example table schema

    Your table needs a date or timestamp column and at least one numeric metric column. Optional string columns work as group-by dimensions.

    ```sql theme={null}
    CREATE TABLE MY_BUSINESS_DB.ANALYTICS.MONTHLY_BUSINESS_METRICS (
      METRIC_DATE DATE,
      ACTIVE_CUSTOMERS NUMBER,
      NEW_CUSTOMERS NUMBER,
      ARR_EUR NUMBER
    );
    ```

    Common metrics to query:

    * Product analytics: daily or monthly active users, sessions, sign-ups
    * Business KPIs: orders, customers, revenue snapshots already in Snowflake
    * Warehouse activity: query counts or bytes scanned by warehouse, team, or query tag

    ## Table requirements

    | Requirement        | Details                                                                                              |
    | ------------------ | ---------------------------------------------------------------------------------------------------- |
    | **Catalog**        | Tables must live in a database listed under **Already visible** on the Snowflake metrics connection. |
    | **Numeric column** | At least one numeric type, such as `NUMBER`, `DECIMAL`, `FLOAT`, or `INTEGER`.                       |
    | **Date column**    | At least one date or timestamp type: `DATE`, `DATETIME`, or `TIMESTAMP` (including `TIMESTAMP_NTZ`). |
    | **Identifier**     | Metric ids in Explorer are `DATABASE.SCHEMA.TABLE`.                                                  |

    ## Query after you connect

    Queries run live through the Snowflake SQL API.

    <Steps>
      <Step title="Open Advanced Explorer">
        Click **Explore your data**, then switch **Classic** to **Advanced**. Classic greys out non-cost metrics.
      </Step>

      <Step title="Add the Snowflake metric">
        Click **+ Add Metric**. Use the **integrations** chip, then pick the Snowflake source. Helper text describes it as a live external usage metric.
      </Step>

      <Step title="Choose a table and columns">
        Pick a **table**, then set **Date field**, **Value column**, **Aggregate** (`SUM`, `AVG`, `MAX`, or `MIN`), **Gap fill** (**FORWARD FILL**, **ZERO**, or **LINEAR**), and optional **Group by**.

        In this example, `MY_BUSINESS_DB.ANALYTICS.MONTHLY_BUSINESS_METRICS` uses date `METRIC_DATE`, value `ACTIVE_CUSTOMERS`, **SUM**, **FORWARD FILL**, and **Last 3 months**. The metric column picker lists every numeric column on the table (`ARR_EUR`, `NEW_CUSTOMERS`, and so on).

        <Frame>
          <img alt="Advanced Explorer with Snowflake metric MY_BUSINESS_DB.ANALYTICS.MONTHLY_BUSINESS_METRICS, date METRIC_DATE, value ACTIVE_CUSTOMERS, and the metric column dropdown open" />
        </Frame>
      </Step>

      <Step title="Add cost or a formula">
        Optionally click **+ Add Metric** for **Cost**, then **+ Add Formula** such as `b / a`. See [Unit Economics](/features/unit-economics).
      </Step>
    </Steps>

    Use the series in a [<Tooltip href="/docs/glossary#virtual-dimensions">virtual dimension</Tooltip>](/features/tagging/dimensions#virtual-dimensions) or [shared cost allocation](/features/tagging/shared-cost-allocation) rule after you can query it in Explorer.

    ## Metric configuration

    | Field            | Description                                                                           |
    | ---------------- | ------------------------------------------------------------------------------------- |
    | **Table**        | Fully qualified Snowflake table (`DATABASE.SCHEMA.TABLE`).                            |
    | **Date field**   | Column used for the time series.                                                      |
    | **Value column** | Column with the metric value.                                                         |
    | **Aggregate**    | How values are rolled up: **SUM**, **AVG**, **MAX**, or **MIN**.                      |
    | **Gap fill**     | How missing dates are filled: **FORWARD FILL**, **ZERO**, or **LINEAR**.              |
    | **Group by**     | Optional string column to split the metric (for example product, team, or warehouse). |

    ## Troubleshooting

    | Issue                       | What to check                                                                                                         |
    | --------------------------- | --------------------------------------------------------------------------------------------------------------------- |
    | **No existing integration** | Connect Snowflake for billing first, then open **Metrics** on the same tile.                                          |
    | **Validate fails**          | Run the grant SQL as **ACCOUNTADMIN**. Confirm the database name matches Snowflake (quoted names are case-sensitive). |
    | **Table does not appear**   | Confirm the table is in a visible database, has both a date and a numeric column, and is not in `INFORMATION_SCHEMA`. |
    | **Chart is empty**          | Pick a different table and change **Period**. Confirm the date column has rows in that range.                         |
  </Tab>

  <Tab title="Terraform">
    Not supported.
  </Tab>
</Tabs>

## Related pages

<CardGroup>
  <Card title="Snowflake billing" icon="database" href="/setup/billing/snowflake">
    Create the key-pair integration this connector reuses.
  </Card>

  <Card title="Unit Economics" icon="calculator" href="/features/unit-economics">
    Combine Snowflake metrics with cloud cost in Explorer formulas.
  </Card>

  <Card title="Shared Cost Allocation" icon="chart-pie" href="/features/tagging/shared-cost-allocation">
    Split shared infrastructure using a Snowflake usage metric.
  </Card>

  <Card title="Metrics Correlation" icon="database" href="/setup/usage-metrics">
    Browse all supported external metric sources.
  </Card>
</CardGroup>


# Tsuga
Source: https://docs.costory.io/setup/usage-metrics/tsuga

Connect Tsuga live cluster metrics to Costory with an Operation API key, then query them in Advanced Explorer.

Connect Tsuga to query metrics, log aggregations, and trace aggregations live in Costory. Use them for <Tooltip href="/docs/glossary#unit-economics">unit economics</Tooltip> or as an allocation key when you split shared costs. The **Tsuga** tile is **Live cluster metrics**.

<Frame>
  <img alt="Connect Tsuga page with Operation API Key field and live-query explanation" />
</Frame>

<Frame>
  <iframe title="Tsuga integration walkthrough" />
</Frame>

<Check>
  Before you begin, make sure you have:

  * A **Tsuga account** with at least one metric, log stream, or trace
  * Permission to create **Operation API Keys** in your Tsuga workspace
</Check>

<Tabs>
  <Tab title="Manual setup">
    <Steps>
      <Step title="Create an Operation API Key in Tsuga">
        Go to [Settings > API Keys](https://app.tsuga.com/settings/api-keys?operation=true) and create a key with the **Operation** type. The value starts with `tsuga_`. Copy it. Tsuga shows the value only once.
      </Step>

      <Step title="Open the Tsuga tile">
        Go to [Integrations](https://app.costory.io/integration), click **+ Add integration**, then under **External metric** choose **Tsuga**. The connect URL is `/integration/new/tsuga/connect`.&#x20;
      </Step>

      <Step title="Connect your workspace">
        Set a **Connection name**, paste the **Operation API Key**, then click **Validate** and **Save connection**. Costory talks to `https://api.tsuga.com`, resolves your cluster, and makes metrics available in Advanced Explorer.
      </Step>
    </Steps>

    ## Query metrics

    Once connected, pick Tsuga in Advanced Explorer (or ask an agent through [Costory MCP](/features/mcp)). Click **+ Add Metric**, open **integrations**, and choose Tsuga. You can group by attributes, paste a Tsuga filter in the condition field, and use the series as a usage driver when splitting a shared cost.

    Costory queries Tsuga live. There is no sync job. Timestamps are UTC. How far back you can go depends on retention in your Tsuga workspace.

    See [Query after you connect](/setup/usage-metrics#query-after-you-connect).

    ## Supported signals

    | Signal  | What you can use                                               |
    | ------- | -------------------------------------------------------------- |
    | Metrics | Counters, gauges, and histograms                               |
    | Logs    | Aggregations from log streams (for example error rate)         |
    | Traces  | Aggregations from distributed traces (for example p99 latency) |

    ## FAQ

    <AccordionGroup>
      <Accordion title="What is an Operation API Key?">
        Tsuga has two key types. **Ingestion** keys are write-only and send data to Tsuga. **Operation** keys are read-only and query data. Costory needs an Operation key that starts with `tsuga_`.
      </Accordion>

      <Accordion title="Can I use log or trace aggregations, not just raw metrics?">
        Yes. Error rate, p99 latency, and similar aggregations work as usage metrics the same way raw metrics do.
      </Accordion>

      <Accordion title="Can I filter by service or environment?">
        Yes. Scope the metric with a Tsuga filter string in the condition field when you build the query or allocation.
      </Accordion>

      <Accordion title="How do I find metric names in my workspace?">
        Call Tsuga's `GET /v1/metrics` endpoint, or browse the API reference at [app.tsuga.com/swagger](https://app.tsuga.com/swagger).
      </Accordion>

      <Accordion title="When will I see data after setup?">
        As soon as the connection validates. Historical range follows the retention configured in your Tsuga workspace.
      </Accordion>
    </AccordionGroup>
  </Tab>

  <Tab title="Terraform">
    Not supported.
  </Tab>
</Tabs>

## Next steps

<CardGroup>
  <Card title="Build unit economics" icon="calculator" href="/features/unit-economics">
    Divide cloud costs by Tsuga metrics (cost per request, cost per user, and similar).
  </Card>

  <Card title="Metrics Correlation" icon="chart-line" href="/setup/usage-metrics">
    Query live external metrics in Advanced Explorer.
  </Card>

  <Card title="Connect events" icon="calendar" href="/setup/events">
    Add deploys and incidents so you can correlate them with metric changes.
  </Card>
</CardGroup>


# Allocate the cost of a shared Cloud SQL database to the teams using it
Source: https://docs.costory.io/use-cases/allocate_shared_cloud_sql_database/allocate

Use Costory's virtual dimensions and usage metrics to split a shared Cloud SQL database cost across consuming teams, based on actual storage or compute usage.

A shared Cloud SQL instance lands as one line on the bill, even when several services query it. A flat split assigns every consumer the same share. That is a misleading <Tooltip href="/docs/glossary#cost-allocation">cost allocation</Tooltip>.

This walkthrough splits Cloud SQL spend with a Datadog usage metric. You preview the formula in **Advanced Explorer**, then store the split as a <Tooltip href="/docs/glossary#virtual-dimensions">virtual dimension</Tooltip> so reports and alerts can reuse it.

<Frame>
  <img alt="Advanced Explorer bar chart with Cost #1, Datadog render.service.cpu.time series, and formula a * b / d allocating Cloud SQL cost" />
</Frame>

## Prerequisites

1. Know what drove the last database cost increase. Use a storage-size metric if storage grew. Use a compute metric if CPU or memory was the constraint.

2. Know where that usage metric lives, for example Datadog or [Google Cloud Monitoring](/setup/usage-metrics/gcp-cloud-monitoring).

3. Have a Datadog connection under **Integrations**. This walkthrough uses the demo connection **Docs Datadog**. To split on a native GCP series instead, connect [GCP Cloud Monitoring](/setup/usage-metrics/gcp-cloud-monitoring) and pick a Cloud SQL metric such as `cloudsql.googleapis.com/database/postgresql/insights/aggregate/execution_time`.

## What you get

* Each service's share of the shared Cloud SQL cost.
* Recurring reports so stakeholders see the allocated split.
* Alerts when a service's share grows unexpectedly.

## Steps

<Steps>
  <Step title="Choose the usage metric">
    Select the metric that matches your cost driver. The tabs below are example queries for Datadog and Google Cloud SQL.

    This walkthrough uses a connected Datadog **render** metric (`render.service.cpu.time`) as the compute-style driver, grouped by `service.name`.

    Storage-size example queries:

    <Tabs>
      <Tab title="Datadog">
        ```
        avg:postgresql.database_size{<yourWhereClause>} by {db}.rollup(avg, daily, 'UTC')
        ```
      </Tab>

      <Tab title="Google Cloud SQL">
        Not available. Use a Datadog-sourced metric instead.
      </Tab>
    </Tabs>

    Compute example queries:

    <Tabs>
      <Tab title="Datadog">
        ```
        sum:postgresql.queries.time{<yourWhereClause>} by {user}.rollup(sum, daily, 'UTC')
        ```
      </Tab>

      <Tab title="Google Cloud SQL">
        ```
        sum by ("user")(
          rate({
            "__name__"="cloudsql.googleapis.com/database/postgresql/insights/aggregate/execution_time",
            "monitored_resource"="cloudsql_instance_database"
          }[${__interval}])
        )
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="Connect the metric as an External metric">
    Go to [Integrations](https://app.costory.io/integration), click **+ Add integration**, then under **External metric** choose **Datadog**. Do not use **Metrics** > **Import new metrics datasource**.&#x20;

    <Frame>
      <img alt="Add integration page showing Billing tiles and an External metric section with Datadog, AWS, GCP, Amplitude, Tsuga, and Google Sheets" />
    </Frame>

    In this walkthrough **Docs Datadog** is already connected, so you can skip the connect form and query the metric in the next step. If you still need to connect Datadog, follow [Datadog metrics](/setup/usage-metrics/datadog), then click **Validate** and **Save connection**.

    <Frame>
      <img alt="Integrations Data sources list showing Docs Datadog with metrics and metrics_ci badges" />
    </Frame>
  </Step>

  <Step title="Add Cloud SQL cost and per-service usage">
    Try the split in **Advanced Explorer** before you store it as a virtual dimension. Click **Explore your data**, then switch to **Advanced**. **Classic** only accepts cost metrics.

    <Note>
      Query Datadog and other [external metrics](/setup/usage-metrics) in **Advanced Explorer** only.
    </Note>

    You will build four series. The formula editor does not support `SUM()`, so the all-services total is its own series. Add cost and per-service usage here. The next step adds the denominator and the formula.

    | Series                    | Role                      | Settings                                                                                                                   |
    | ------------------------- | ------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
    | **Cost #1 (a)**           | Shared Cloud SQL cost     | **Metric** **Cost**, **Aggregate** **SUM**, **Group By** **Service Name**, **Where** **Service Name** **In** **Cloud SQL** |
    | **Externalmetric #2 (b)** | This service's usage      | **Docs Datadog**, `render.service.cpu.time`, **Aggregate** **SUM**, **Group by** `service.name`                            |
    | **Formula #3 (c)**        | Allocated cost            | `a * b / d`                                                                                                                |
    | **Externalmetric #4 (d)** | Usage across all services | Same `render.service.cpu.time` metric, **Aggregate** **SUM**, **Group by** **None**                                        |

    `a * b / d` is shared Cloud SQL cost times this service's `cpu.time`, divided by all services' `cpu.time`.

    Configure **Cost #1 (a)** as in the table. Open **Where** and set **Service Name** **In** **Cloud SQL**.

    <Frame>
      <img alt="Advanced Explorer Cost #1 row with Where popover set to Service Name In Cloud SQL and a Cloud SQL bar chart" />
    </Frame>

    Click **+ Add Metric**, open **integrations**, and choose **Docs Datadog**. Search `render`, then pick `render.service.cpu.time`. Set **Aggregate** to **SUM** and **Group by** to `service.name`.

    <Frame>
      <img alt="Advanced Explorer Datadog metric picker searching render and listing render.service.cpu.time" />
    </Frame>

    <Frame>
      <img alt="Advanced Explorer dual-axis chart of Cloud SQL cost and Datadog render.service.cpu.time grouped by service.name" />
    </Frame>

    Use **SUM** when you later aggregate this metric at weekly or monthly levels. A maximum aggregation can over-allocate cost to the service that spiked on a single day.
  </Step>

  <Step title="Add the usage total and the allocation formula">
    Click **+ Add Metric** again. Pick the same **Docs Datadog** metric `render.service.cpu.time`, **Aggregate** **SUM**, **Group by** **None**. That series is **Externalmetric #4 (d)**, the denominator.

    Set **Formula #3 (c)** to `a * b / d`. Toggle the checkboxes on each series so you can inspect the allocated series on its own.

    <Frame>
      <img alt="Advanced Explorer with Cost a, Datadog series b grouped by service.name, formula a * b / d, and Datadog series d grouped by None" />
    </Frame>
  </Step>

  <Step title="Create a virtual dimension scoped to Cloud SQL">
    Store the split so you can reuse it in group-bys, reports, and alerts.

    Go to [Dimensions](https://app.costory.io/dimensions), click **+ Add new dimension**, then **Virtual dimension**.&#x20;

    <Frame>
      <img alt="Dimensions page Add new dimension menu with Dimension and Virtual dimension options" />
    </Frame>

    Name it **cloud sql reallocated**. The modal accepts lowercase letters, numbers, and underscores.

    <Frame>
      <img alt="Create a new dimension modal with Name set to cloud sql reallocated" />
    </Frame>

    On **Rule 1**, set the condition **Where** **Service Name** **In** **Cloud SQL**. That scopes the shared cost this rule reallocates.

    Open **Allocate costs by:** and select **Dynamic based on usage metric**. That is <Tooltip href="/docs/glossary#dynamic-allocation">Dynamic Allocation</Tooltip>: Costory splits the scoped cost in proportion to the usage series.

    <Frame>
      <img alt="Virtual dimension Rule 1 Allocate costs by menu listing Direct value, Split cost, Existing value, and Dynamic based on usage metric" />
    </Frame>

    Set **Integration** to **Docs Datadog**, **Metric** to `render.service.cpu.time`, and **Split by** to `service.name`. **Aggregate** stays **SUM**.

    <Frame>
      <img alt="cloud sql reallocated Rule 1 with Dynamic based on usage metric and the Datadog metric list filtered to render" />
    </Frame>
  </Step>

  <Step title="Map metric values and save a draft">
    Map Datadog `service.name` values to dimension values. You can use identity pass-through, a regex, or a manual map.

    | Mapping                 | How you set it                                                               | When to use                                                       |
    | ----------------------- | ---------------------------------------------------------------------------- | ----------------------------------------------------------------- |
    | Identity (pass-through) | Click **Switch to identity**, or check **Set with Regex** and keep `[\s\S]*` | `service.name` values are the dimension values you want           |
    | Regex                   | Check **Set with Regex** and edit the pattern                                | You need to extract a team or service token from the metric value |
    | Manual                  | Pick **Select a value** for each metric label                                | Labels have no relation to the dimension values                   |

    <Frame>
      <img alt="Rule 1 mapping list for costory-app-back and costory-app-back-prod with Select a value dropdowns and Mapping is required" />
    </Frame>

    This walkthrough uses identity pass-through: check **Set with Regex** and keep `[\s\S]*`. The helper text reads **Identity pass-through: metric values are used as dimension values (regex \[\s\S]\*).**

    <Frame>
      <img alt="Rule 1 with Set with Regex checked and the pattern that passes metric values through as dimension values" />
    </Frame>

    <Frame>
      <img alt="Completed cloud sql reallocated Rule 1 with Docs Datadog render.service.cpu.time, Split by service.name, and identity regex mapping" />
    </Frame>

    <Warning>
      If you choose manual mapping and a new service appears later, edit the virtual dimension to map that service.
    </Warning>

    Click **Save draft**. A draft does not appear in Explorer group-by until you **Publish**. This walkthrough stops at the draft.

    <Tip>
      The [Costory MCP](/features/mcp) can build this from chat: "draft a virtual dimension that allocates my shared Cloud SQL cost using render.service.cpu.time grouped by service.name, preview it, then save a draft."
    </Tip>
  </Step>

  <Step title="Publish and create a report">
    After you **Publish**, go to [Explorer](https://app.costory.io/explorer) and create a new report grouped by **cloud sql reallocated**. You can also schedule the report to Slack on a weekly or monthly basis. See [Cost Reports](/features/slack-reports).&#x20;
  </Step>
</Steps>

## Troubleshooting

<AccordionGroup>
  <Accordion title="The dimension does not appear in Explorer group-by">
    A draft is not available as a group-by. Open the virtual dimension and click **Publish** after you finish editing.
  </Accordion>

  <Accordion title="The formula editor rejects SUM()">
    The editor does not support `SUM()` inside a formula. Add the all-services total as its own series (**Externalmetric #4**) with **Group by** **None**, then divide by that series (`d`).
  </Accordion>

  <Accordion title="A new service appears after you save">
    Identity pass-through picks up new `service.name` values on the next run. Manual mapping does not. Edit the virtual dimension and map the new label.
  </Accordion>
</AccordionGroup>

## Related

* To allocate a shared API instead of a database, see [Split Shared API Costs Across Teams](/use-cases/reallocate_api_costs). That guide uses an external usage metric such as API call counts.
* Connect Datadog or another usage source from [usage metrics](/setup/usage-metrics).
* See [Shared Cost Allocation](/features/tagging/shared-cost-allocation) for mapping types and other shared infrastructure patterns.
* Virtual dimension rules live in [Dimensions](/features/tagging/dimensions#virtual-dimensions).


# Correlate Cloud Costs with Active Users Using Amplitude
Source: https://docs.costory.io/use-cases/amplitude/cost_per_active_users

Understand whether your cloud costs scale with your business. Connect Amplitude active users to Costory and track cost per thousand users over time.

Cloud cost per active user tracks whether your infrastructure scales the way it should. If spend rises 30% while active users grow 50%, cost per user drops and efficiency improves. If users stay flat and costs still climb 30%, that gap is worth a look.

<iframe title="Track cloud cost per active user with Amplitude" />

Link your spend to a core business metric to see what is happening. That ratio is your <Tooltip href="/docs/glossary#unit-economics">unit economics</Tooltip>.

| Costs | Users | Cost / 1k users | Verdict               |
| ----- | ----- | --------------- | --------------------- |
| +30%  | +50%  | down            | Scaling well          |
| +30%  | +30%  | flat            | No gain, no loss      |
| +30%  | +10%  | up              | Drifting, investigate |

The right metric correlates most closely with your cloud spend: when it goes up, costs go up proportionally. If they don't, that is a problem worth investigating.

Pick the metric that maps to what your infrastructure serves:

* **SaaS / Product**: DAU or MAU.
* **E-commerce**: orders processed.
* **Fintech**: transactions processed.
* **API platform**: API requests.
* **Marketing**: campaigns or emails sent.
* **Ad tech**: impressions served or ad revenue.
* **Data / Analytics**: queries or pipelines executed.
* **Streaming / Gaming**: hours streamed or concurrent players.

<Tip>
  Don't stop at the global ratio. Break it down **per team, per region, or per workflow step**. A healthy global number can hide that one team or one region is drifting badly.
</Tip>

This guide walks through the setup with **active users from Amplitude**, a hands-on example of [tracking unit economics](/automate-reporting/unit-economics). The same approach works with any metric you connect under **Integrations** > **External metric**.

## What you'll get

* A chart that overlays production costs with active users and cost per thousand users. Divergences are visible at a glance.
* Recurring Cost Reports showing cost and user trends side by side, without spreadsheet work.
* An alert that fires when your cost per thousand active users crosses a threshold you define.

## Prerequisites

* **Amplitude API credentials**: API key + secret from Amplitude > Settings > Projects > \[Your Project] > General. Used by the [Amplitude connector](/setup/usage-metrics/amplitude) to query daily active users live in Costory.

* **A production cost filter**: a where clause in [Explorer](/features/cost-explorer) that isolates prod workloads. Exclude R\&D, staging, and marketplace purchases, as they distort the unit cost calculation.

## How to track cloud cost per active user

<Steps>
  <Step title="Connect Amplitude and query active users">
    Go to [Integrations](https://app.costory.io/integration), click **+ Add integration**, then under **External metric** choose **Amplitude**. Enter your API key, secret key, and region. See [Amplitude](/setup/usage-metrics/amplitude).&#x20;

    Click **Explore your data**, switch to **Advanced**, then **+ Add Metric**. Open **integrations**, pick Amplitude, and add active users as **query a**. Set the aggregation to **Average**. You want the typical user count over the period, not a peak or a sum.

    <Info>
      A metric can include one or more **group-by dimensions** (e.g., region, plan tier, team). When you add a group-by, Costory queries the metric broken down by that dimension, so you can later compute cost per thousand users **per segment** instead of only at the global level.
    </Info>

    <Info>
      Not using Amplitude? Connect any source on the [External metric](/setup/usage-metrics) grid: Datadog, Datadog CI Visibility, BigQuery, Google Sheets, Tsuga, CloudWatch, or S3.
    </Info>
  </Step>

  <Step title="Build the cost per thousand users formula">
    Your active users are already loaded as **query a**. Add a Cost query as **query b**, filtered to production, for example `Environment in Production`. Then add a formula **`b / (a / 1000)`** to get cost per thousand users. Dividing by 1,000 gives a more readable number than cost per individual user.

    <Tip>
      Keep the cost scope tight. If you include non-production spend (R\&D, staging, marketplace), the ratio will fluctuate for reasons unrelated to user-facing efficiency.
    </Tip>

    <Tip>
      You can build this cost-per-1k-users view from chat with the [Costory MCP](/features/mcp): "plot my production cost against Daily Active Users and add a formula for cost per thousand users, then save it as a dashboard."
    </Tip>
  </Step>

  <Step title="Save as a view and schedule to Slack">
    Save as a <Tooltip href="/docs/glossary#view">View</Tooltip>, for example "Production Cost per Thousand Users", and schedule weekly or monthly delivery to Slack.
  </Step>

  <Step title="Set an alert for efficiency regressions">
    Click the bell icon on the same view. Set a threshold on cost per thousand users. Costory notifies you when the ratio crosses it, so you catch efficiency regressions before they compound.
  </Step>
</Steps>

## FAQ

<AccordionGroup>
  <Accordion title="Which business metric should I use for unit economics?">
    Pick the metric that correlates most closely with your cloud spend. For most SaaS products, that's daily or monthly active users. For e-commerce it may be orders processed, for API platforms it's API requests, and for data platforms it's queries executed. If the metric goes up and costs go up proportionally, you've found the right one.
  </Accordion>

  <Accordion title="Can I use this without Amplitude?">
    Yes. Connect any source on the [External metric](/setup/usage-metrics) grid: Datadog, Datadog CI Visibility, BigQuery, Google Sheets, Tsuga, CloudWatch, or S3.
  </Accordion>

  <Accordion title="How often does the Amplitude metric update?">
    Queries run live. Costory does not sync an Amplitude time series to BigQuery.
  </Accordion>

  <Accordion title="Should I use Average or Sum for the aggregation?">
    Use **Average** for user counts. It gives you the typical user count over the period rather than a peak or cumulative total. Use **Sum** for volume-based metrics like API requests or transactions processed.
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup>
  <Card title="Cost Reports" icon="paper-plane" href="/features/slack-reports">
    Send weekly or monthly cost reports to your team channels.
  </Card>

  <Card title="Explore cost drivers" icon="chart-line" href="/features/cost-explorer">
    Drill into cost spikes and validate trends across services.
  </Card>

  <Card title="Improve tagging" icon="tags" href="/features/tagging">
    Clean up labels and boost attribution accuracy.
  </Card>
</CardGroup>


# Cloud budget management: define and automate cloud budgets
Source: https://docs.costory.io/use-cases/automate_budget

Learn how to set up cloud budget management per team with automated alerts, monthly reports, and FinOps budgeting best practices.

This guide sets up per-team cloud budgets in Costory: pick a cost dimension, set the values, share them, and alert when a team goes over. It takes you from one central budget to a per-team workflow.
For the product overview, see [Budgets](/features/budgets).

## Context

* You have a central budget owned by a single person responsible for the entire company spending.
* You want to give them more autonomy to manage their own spending.
* You want to increase the accountability of each team.

## Prerequisites

* You have set up the Slack or Teams integration to share reports with the teams.
* You can split your bill per budget line (team, sub product, etc.).

## What you can expect

* Budget per month to be shared with the team.
* Automated monthly reports to increase visibility for each team.
* Alerting if a team is over budget.

## Steps

<Steps>
  <Step title="Choose a dimension to budget your costs">
    There is no ideal dimension to budget your costs: you should choose a dimension that makes sense for your organization and your yearly goals:

    | Scenario                                       | Recommended budget dimension                                               |
    | ---------------------------------------------- | -------------------------------------------------------------------------- |
    | You're launching a new product this year       | Per product and per environment (prod / R\&D)                              |
    | You're migrating to a new stack                | Per project (new migration / existing stack / R\&D)                        |
    | The billing ownership is clear by team         | Per team (Engineering / ML / Data)                                         |
    | You're upselling your customers on AI features | Per product category and per environment (AI prod / AI R\&D / Prod / R\&D) |

    <Tip>
      * **Keep a buffer** Add in your budget a buffer to account for new projects, unexpected errors etc... 5% of overall budget is a good starting point.
      * **Use a stable attribution**: This is not the time to find the best attribution strategy for your shared database. Split the costs in a simple way: attribution should be easy. Use [dimensions](/features/tagging/dimensions) to create simple team-level groupings without re-tagging your cloud resources.
      * **Share the division with the team**: they need to understand the attribution. If your virtual dimension is too complex, they won't trust it.
      * **Take into account credits** (yearly credits, migration plan, etc.). Two options: exclude them fully, or keep them in a separated budget line. See [Cost Metrics](/docs/cost-metrics) for a full comparison of how each metric handles credits and discounts.
      * **Handle savings plans carefully**: if you have a global savings plan over all your accounts, it can be assigned to different accounts over time, creating fake cost variations. Use <Tooltip href="/docs/savings-plan-cost-fluctuation">Contracted Cost</Tooltip> for a metric that is stable against savings plan movements.
    </Tip>
  </Step>

  <Step title="Define the budget values">
    1. Instantiate a budget in Costory, this will allow you to export the historical cost per budget line over last 12 months and help you forecast;
    2. Pick the best strategy to budget:

    | Scenario                                                                                                                                                                 | Approach                                                                                                                                                              |
    | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | **General budget increase** (fixed % over current spend)                                                                                                                 | Apply the increase incrementally across each month's budget (pro-rata distribution).                                                                                  |
    | **Production costs** (cost per user/activity)                                                                                                                            | Use [Explorer](/features/cost-explorer) to find the historical cost-per-user ratio, then multiply by Finance's user forecast with a small decrease of marginal costs. |
    | **R\&D CI costs** (cost per engineer/CI hours)                                                                                                                           | Correlate spend with engineer count and CI hours                                                                                                                      |
    | **Fast-growing product** ([Spotify's cost-vs-growth approach](https://engineering.atspotify.com/2020/09/managing-clouds-from-the-ground-up-cost-engineering-at-spotify)) | Don't budget cost but **marginal cost** (cost per user/transaction). A rising bill is healthy if cost-per-unit decreases.                                             |
    | **Budget in units, not dollars** ([Indeed talk](https://www.youtube.com/watch?v=exxxlTwqzrs))                                                                            | Budget each big category using consumption units (API calls, compute-hours, GB) for your most expensive services. Convert to `$` only for Finance reporting.          |

    3. Assign an owner to each budget line.
  </Step>

  <Step title="Share the budget with the team">
    * **Validate the budget with the team**: Before locking it in, align with each team on the budget values and the dimension (environment, product, or team) so they understand and accept their targets.
    * **Share the budget on a schedule**: Once owners are assigned (see previous step), share the budget with the team regularly, for example via a [weekly Slack report](/features/slack-reports) or a recurring email, so everyone sees their budget status and stays accountable.
  </Step>

  <Step title="Be alerted if you exceed your budget">
    Create a budget alert so that when the monthly budget is exceeded or forecast to be exceeded, the alert reaches the overall budget owner and each budget line owner through Slack or email.

    <Tip>
      You can create a threshold alert without leaving chat. Ask the [Costory MCP](/features/mcp) to "preview an alert if the platform team's monthly cost goes over \$50,000, then create it." It backtests against history before anything goes live.
    </Tip>
  </Step>

  <Step title="Update the budget quarterly">
    Every beginning of quarter, review the budget. If a team consistently overspends, take this into account and update your forecast accordingly.

    * Create a new version of the budget.
    * Align past costs with the updated budget and check if the forecast still makes sense.

    <Tip>
      What to do with unused costs? You can either:

      * Keep them in a buffer budget line to be used for unexpected expenses.
      * Move them to a different budget line to be used for a different purpose.
    </Tip>
  </Step>
</Steps>

## What's next?

* Set up a [weekly Slack report](/features/slack-reports) to share budget status with each team.
* Explore your data in [Explorer](/features/cost-explorer) to identify cost drivers per team.


# Automated env allocation
Source: https://docs.costory.io/use-cases/automated_env_allocation/visibility

How to easily allocate your costs per environment using all the metadatas available in your billing data

## Prerequisites:

* If you have an AWS provider connected to Costory, you enabled in [Cost Allocation tags](https://console.aws.amazon.com/billing/home#/tags) AWS UI all the tags available.
* If you're using the same Kubernetes cluster for all your environments, you have a way to identify the environment of the pod using a namespace / or a label attached to the pod.
* You identified which marketplace purchases are required for your production environment.

## Output:

* You can compute your cost per environment either using only labels, or using a virtual dimension.
* You can schedule monthly reports to share with your team to monitor the cost of each environment.
* Your Digest will surface the cost changes for each environment.

## Steps:

<Steps>
  <Step title="Step 1: Ingest the env-related labels in your billing data">
    When you connect your billing data, Costory analyzes every available label and finds the ones tied to environments.

    <img alt="Auto Ingest" />

    Automatic feature engineering includes:

    * Merge columns from multiple sources into a single label: `k8s_label_env` with `env` and `environment`, `environnment`...
    * Rename values to standardize naming across providers: `stg`-> `staging`, `dev`-> `development`, `prod`-> `production`...
      <img alt="Auto Ingest" />
  </Step>

  <Step title="Step 2: Create a virtual dimension to allocate the leftover costs">
    Some of your costs might not be allocated using those labels:

    * either because they can't (network costs, Datadog, etc.)
    * or because they would require an additional split (for example a marketplace purchase used in both prod and staging) that you need to share.

    To fill this gap, you can create a virtual dimension to allocate those costs:

    <img alt="Virtual Dimension" />
  </Step>

  <Step title="Step 3: Create a report to visualize the cost allocation">
    Once costs are allocated per environment, you can:

    * [Share a report with your exec team](/use-cases/what_your_exec_team_wants/value)
    * [Calculate marginal cost of your prod app using an external metric](/use-cases/amplitude/cost_per_active_users)

      <img alt="Examples" />
  </Step>
</Steps>


# Increase visibility on your BigQuery costs with dbt
Source: https://docs.costory.io/use-cases/dbt_bigquery_visibility/increase_visibility

Track and allocate BigQuery processing and storage costs at the dbt model level using labels, then visualize them in Costory.

When you run dbt on BigQuery, it is hard to know which models drive the most cost. BigQuery billing exports show project-level and dataset-level spend, with no model-level granularity. This guide uses BigQuery labels and dbt macros to break down processing and storage costs by model, team, package, or any custom dimension.

## Prerequisites

* You are using **[dbt](https://www.getdbt.com/)** to orchestrate your BigQuery workloads.
* Your GCP billing export is [connected to Costory](/setup/billing#gcp).

## Output

* Cost visibility broken down by dbt model, team, package, or any custom label.
* Ability to identify which models drive auto-scaling or high processing costs.
* Foundation for cost allocation and optimization.

## Steps

<Steps>
  <Step title="Label your dbt operations in BigQuery">
    Configure automated labels in your `dbt_project.yml` so every query is tagged with dbt native metadata:

    ```yaml theme={null}
    query-comment:
      comment: "{{ bq_labels(node, var) }}"
      job-label: True
    ```

    Then create a macro `bq_labels` to populate the labels automatically. Here is all the information you can use:

    | Object         | Property                                    | Description                                                                                                  |
    | -------------- | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
    | Node           | node.original\_file\_path                   | The original file path of the node                                                                           |
    | Node           | node.name                                   | The name of the node                                                                                         |
    | Node           | node.resource\_type                         | The resource type of the node (`model`, `test`, `seed`, `snapshot`, `table`)                                 |
    | Node           | node.package\_name                          | The dbt package name                                                                                         |
    | Node           | node.database                               | For BigQuery, this is the project name of the project on which you write                                     |
    | Node           | node.schema                                 | The dbt schema of the node                                                                                   |
    | env\_var macro | ex: env\_var('username','cloud\_run\_task') | Any env var available at runtime                                                                             |
    | var macro      | ex: var('customer', 'test')                 | Any dbt variable available at runtime                                                                        |
    | target         | target.get('profile\_name')                 | The profile name of the target (useful if you split per target your ingested / full refresh / backfill jobs) |
    | target         | target.get('target\_name')                  | The target name of the target                                                                                |

    ```sql theme={null}
    {% macro bq_labels(node, var) %}
        {%- set comment_dict = {} -%}
        {%- do comment_dict.update(
            app='background_tasks',
            customer=var('customer', 'test'),
            repository="analytics",
            processed_by=env_var('username','cloud_run_task'),
            profile_name=target.get('profile_name'),
            target_name=target.get('target_name')
        ) -%}
        {%- if node is not none -%}
          {%- do comment_dict.update(
            file=node.original_file_path,
            node_id=node.unique_id,
            node_name=node.name,
            resource_type=node.resource_type,
            package_name=node.package_name,
            database=node.database,
            schema=node.schema
          ) -%}
        {%- endif -%}
        {% do return(tojson(comment_dict)) %}
    {% endmacro %}
    ```

    This macro will label every query run during the dbt run.
  </Step>

  <Step title="Label your storage resources">
    In BigQuery, storage costs are visible at the dataset level using `resource_id` / `resource_name`, but they are not visible at the billing level per table. To add labels at the table level, apply them in your dbt model config:

    ```sql theme={null}
    {{
      config(
        tags=["ingestion"],
        materialized='table',
        labels={'maintained_by': 'team_A'}
      )
    }}
    ```

    You can also set labels at the `dbt_project.yml` level. Note that project-level labels will override model-level labels if both are set.
  </Step>

  <Step title="Visualize your labeled job costs without Costory">
    Use BigQuery's `INFORMATION_SCHEMA` to analyze costs by label:

    ```sql theme={null}
    SELECT
        ARRAY((SELECT value FROM UNNEST(labels) WHERE key = "label_name"))[SAFE_OFFSET(0)] AS label,
        SUM(total_slot_ms) AS total_slot_ms,
        SUM(total_bytes_billed) AS total_bytes_billed
    FROM `<your_project>`.`region-eu`.INFORMATION_SCHEMA.JOBS_BY_PROJECT
    WHERE EXTRACT(DATE FROM creation_time) = CURRENT_DATE()
        AND ARRAY((SELECT value FROM UNNEST(labels) WHERE key = "label_name"))[SAFE_OFFSET(0)] IS NOT NULL
    GROUP BY 1
    ```

    To query storage-level labels on tables:

    ```sql theme={null}
    SELECT
        *,
        ARRAY((SELECT AS STRUCT json[0] AS key, json[1] AS value
               FROM UNNEST(ARRAY(
                   (SELECT AS STRUCT JSON_VALUE_ARRAY(CONCAT('[', elements, ']')) AS json
                    FROM UNNEST(regexp_extract_all(option_value, r'STRUCT\("[^"]+", "[^"]+"\)')) elements)
               )))) AS labels
    FROM
        <your_project>.INFORMATION_SCHEMA.TABLE_OPTIONS
    WHERE option_name = 'labels'
    ```
  </Step>

  <Step title="Visualize your labeled job costs with Costory">
    1. Ingest the labels into Costory using the feature engineering UI:

       <img alt="Costory feature engineering screen showing how to ingest BigQuery labels from dbt models" />

    2. If part of your BigQuery labels should be merged within an existing label, use the merge feature to combine two labels into one (e.g., `k8s_label_app` and `app`).

    3. [Create a virtual dimension](/features/tagging/dimensions#virtual-dimensions) to allocate the cost, or explore costs directly in [Explorer](/features/cost-explorer):

       <img alt="Costory Explorer showing BigQuery costs broken down by dbt model, team, and package labels" />

    <Tip>
      To investigate a spike without opening Explorer, ask the [Costory MCP](/features/mcp): "split last week's BigQuery cost by the `node_name` label and show the top 10 dbt models."
    </Tip>
  </Step>
</Steps>

## Best practices

### Labels

* Ingest `node_name` for fine-grained cost investigation to understand which exact model is driving cost.
* Use `package_name` or `schema` to map each schema to the correct team or owner. You can formalize this mapping with [virtual dimensions](/features/tagging/dimensions#virtual-dimensions).
* Use `target_name` to split daily jobs, full refreshes, and backfills.

### Quotas

* Set a quota on GCP for query bytes billed per service account or per user using [`QueryUsagePerUserPerDay`](https://docs.cloud.google.com/bigquery/docs/custom-quotas).

### Alerts

* Set an alert close to the daily average on ingestion costs. Daily ingestion jobs should be very stable.
* For full refresh jobs, evaluate alerts over a larger period to avoid false positives from spikes.

### Storage costs

* Evaluate storage costs frequently. After 90 days the storage price decreases, but if you never read the data you should rely on an expiration policy instead.
* Since 2023, you can choose per dataset the [storage billing model](https://docs.cloud.google.com/bigquery/docs/updating-datasets#update_storage_billing_models):
  * **Logical storage**: you pay based on the logical size (before compression).
  * **Physical storage**: you pay based on the physical size (after compression).

You can compare both costs using the following SQL query. Run it per region and change the `region-us` suffix:

```sql theme={null}
DECLARE active_logical_gib_price FLOAT64 DEFAULT 0.02;
DECLARE long_term_logical_gib_price FLOAT64 DEFAULT 0.01;
DECLARE active_physical_gib_price FLOAT64 DEFAULT 0.04;
DECLARE long_term_physical_gib_price FLOAT64 DEFAULT 0.02;
WITH storage_sizes AS (
SELECT
  table_schema AS dataset_name,
  SUM(active_logical_bytes) / POWER(1024, 3) AS active_logical_gib,
  SUM(long_term_logical_bytes) / POWER(1024, 3) AS long_term_logical_gib,
  SUM(active_physical_bytes) / POWER(1024, 3) AS active_physical_gib,
  SUM(long_term_physical_bytes) / POWER(1024, 3) AS long_term_physical_gib,
  SUM(time_travel_physical_bytes) / POWER(1024, 3) AS time_travel_physical_gib,
  SUM(fail_safe_physical_bytes) / POWER(1024, 3) AS fail_safe_physical_gib
FROM
  `region-us`.INFORMATION_SCHEMA.TABLE_STORAGE_BY_PROJECT
WHERE table_type = 'BASE TABLE'
GROUP BY 1
)
SELECT
  dataset_name,
  ROUND((active_logical_gib * active_logical_gib_price) + (long_term_logical_gib * long_term_logical_gib_price), 2) AS monthly_cost_logical,
  ROUND(
    (active_physical_gib * active_physical_gib_price) +
    (long_term_physical_gib * long_term_physical_gib_price) +
    ((time_travel_physical_gib + fail_safe_physical_gib) * active_physical_gib_price), 2
  ) AS monthly_cost_physical,
  ROUND(SAFE_DIVIDE(active_logical_gib + long_term_logical_gib, active_physical_gib + long_term_physical_gib), 2) AS compression_ratio
FROM
  storage_sizes
ORDER BY
  monthly_cost_logical DESC;
```

Tabular data with frequent values usually compresses well, so the physical cost is typically lower than the logical cost.

If you find a dataset that would be significantly cheaper under the physical model:

```sql theme={null}
ALTER SCHEMA my_dataset SET OPTIONS(storage_billing_model = 'physical');
```

<Warning>
  Changes take about 24 hours to affect billing. Once you switch, you must wait
  14 days before you can switch back.
</Warning>

## Next steps

* [Explore your costs in Explorer](/features/cost-explorer): slice and dice your BigQuery spend with full context.
* [Tag & allocate costs with dimensions](/features/tagging/dimensions): map labels to teams and build cost allocation rules.
* [Allocate shared Cloud SQL costs across teams](/use-cases/allocate_shared_cloud_sql_database/allocate): apply similar labeling strategies to Cloud SQL.
* [Get Kubernetes cost visibility with EKS](/use-cases/eks-cost-allocation): extend cost tracking to your container workloads.

## FAQ

<AccordionGroup>
  <Accordion title="What BigQuery labels does dbt support?">
    dbt supports **job-level labels** via `query-comment` in `dbt_project.yml` and **table-level labels** via the `labels` property in model `config()`. Job labels appear in `INFORMATION_SCHEMA.JOBS_BY_PROJECT`, while table labels appear in `INFORMATION_SCHEMA.TABLE_OPTIONS`.
  </Accordion>

  <Accordion title="What's the difference between physical and logical storage costs?">
    Physical storage costs are the costs of the data stored in BigQuery. Logical storage costs are the costs of the data stored in BigQuery after compression. You can compare both costs using the SQL query above.
    Usually tabular data with frequent values compresses well, so the physical cost is typically lower than the logical cost.
  </Accordion>

  <Accordion title="How do I set a BigQuery cost quota?">
    Use GCP's custom quotas feature with [`QueryUsagePerUserPerDay`](https://docs.cloud.google.com/bigquery/docs/custom-quotas) to limit bytes billed per user or service account per day.
  </Accordion>

  <Accordion title="Will project-level labels override model-level labels?">
    Yes. Labels set in `dbt_project.yml` at the project level will override labels set in individual model `config()` blocks if both define the same key.
  </Accordion>

  <Accordion title="Can I track BigQuery costs per query when using Slots?">
    When using slots, you will need to reattribute the slots costs to each query. You can do this using [virtual dimensions](/features/tagging/dimensions#virtual-dimensions). A native connector is under development to do it natively.
  </Accordion>
</AccordionGroup>


# AWS EKS Cost Allocation
Source: https://docs.costory.io/use-cases/eks-cost-allocation

Compare EKS cost allocation methods for Kubernetes cost visibility, including AWS Split Cost Allocation, AWS-managed usage metrics, and Kubecost or OpenCost.

EKS cost allocation helps you see which pods, namespaces, and teams use shared cluster capacity. This guide compares AWS Split Cost Allocation, AWS-managed usage metrics, and Kubecost or OpenCost so you can choose the right Kubernetes cost visibility method and normalize the result in Costory.

<img alt="Costory Explorer showing EKS costs grouped by team and application" />

*Use EKS labels to group cluster costs by team, application, or environment in Costory.*

## Prerequisites

* You have an **AWS EKS** cluster running.
* You have an AWS provider connected to Costory with your [<Tooltip href="/docs/glossary#cur">CUR</Tooltip> data](/setup/billing#aws) ingested.
* You have labels or tags applied to your pod deployments, or you plan to add them.
* For Kubecost or OpenCost, you can export allocation data to a shared S3 bucket that Costory can access.

## Output

* Granular cost visibility at the Kubernetes label level, including team, app, environment, namespace, and cluster.
* A clear choice between request-based, usage-based, and OpenCost-backed allocation.
* Ability to track <Tooltip href="/docs/glossary#waste-ratio">waste ratio</Tooltip> per node pool and identify over-provisioned clusters.
* Foundation for <Tooltip href="/docs/glossary#cost-allocation">cost allocation</Tooltip> and <Tooltip href="/docs/glossary#chargeback">chargeback</Tooltip> across teams.
* Stable cost data using [Contracted Cost](/docs/savings-plan-cost-fluctuation), so Savings Plan reassignments between clusters do not create false cost spikes.

## Choose an EKS cost allocation method

Pick the method that matches the allocation signal you trust most: Kubernetes requests, measured CPU and memory usage, or OpenCost allocation data.

| Option                                                                                                          | How it works                                                                                                                                                                                                                                              | Best for                                                                                                        | Limitations                                                                                                          |
| --------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| AWS <Tooltip href="/docs/glossary#split-cost-allocation">Split Cost Allocation</Tooltip> with Kubernetes labels | AWS adds pod-level cost records to your <Tooltip href="/docs/glossary#cur">CUR</Tooltip> based on requested CPU and memory. EKS Kubernetes labels can be activated as <Tooltip href="/docs/glossary#cost-allocation-tags">Cost Allocation Tags</Tooltip>. | Fast setup when you want agentless EKS cost allocation in billing data.                                         | Costs follow requests, not actual usage. Over-requesting workloads can receive more cost than they consume.          |
| AWS-managed usage metrics                                                                                       | AWS reads CPU and memory usage metrics from CloudWatch or Amazon Managed Service for Prometheus, then uses those metrics for split cost allocation.                                                                                                       | Teams that want allocation closer to actual CPU and memory consumption while keeping AWS billing as the source. | Requires a metrics collector or agent in the cluster. Direct outbound network costs are not split at workload level. |
| Kubecost or OpenCost                                                                                            | You install the Kubecost or OpenCost agent on each cluster, then export allocation data to a shared S3 bucket that Costory can access.                                                                                                                    | Clusters where outbound network costs or Kubernetes-native allocation reports are material.                     | Requires agent management, export jobs, and access to a shared storage location.                                     |

<Info>
  If you are starting from scratch, start with AWS <Tooltip href="/docs/glossary#split-cost-allocation">Split Cost Allocation</Tooltip>. Add usage metrics or OpenCost data only when requests are too coarse or network allocation is material.
</Info>

## Recommended labels for EKS chargeback

Start with a small label set that answers who owns the workload, what it runs, and where it runs. You can add more labels later, but these fields cover most EKS <Tooltip href="/docs/glossary#cost-allocation">cost allocation</Tooltip> workflows.

| Label              | Example values                 | Use it to                                                   |
| ------------------ | ------------------------------ | ----------------------------------------------------------- |
| `team`             | `platform`, `data`, `payments` | Route costs to the right engineering or product team.       |
| `app` or `service` | `api`, `worker`, `checkout`    | Find which service drives spend inside a team.              |
| `env`              | `production`, `staging`, `dev` | Separate production costs from non-production usage.        |
| `cluster`          | `prod-eu`, `shared-us`         | Compare clusters and find placement issues.                 |
| `namespace`        | `payments`, `observability`    | Allocate shared cluster costs when teams map to namespaces. |

Use consistent lowercase values. Avoid aliases like `prod`, `prd`, and `production` unless you plan to normalize them in <Tooltip href="/docs/glossary#dimensions">Dimensions</Tooltip>.

## Set up your chosen EKS cost allocation method

<Steps>
  <Step title="Configure the allocation data source">
    <Tabs>
      <Tab title="AWS Split Cost Allocation">
        AWS Split Cost Allocation adds pod-level cost records to your <Tooltip href="/docs/glossary#cur">CUR</Tooltip>. Kubernetes custom labels for EKS became available as cost allocation tags in October 2025, so you can attribute EKS costs by business labels such as team, application, and environment.

        1. Go to the [AWS Cost and Usage Report settings](https://console.aws.amazon.com/billing/home#/tags).
        2. Follow the [AWS guide for enabling split cost allocation data](https://docs.aws.amazon.com/cur/latest/userguide/enabling-split-cost-allocation-data.html).
        3. Include resource IDs and use hourly reports when you need the most granular data.
        4. Activate the relevant <Tooltip href="/docs/glossary#cost-allocation-tags">Cost Allocation Tags</Tooltip> in the Billing console.
      </Tab>

      <Tab title="AWS-managed usage metrics">
        AWS can read CPU and memory usage metrics from CloudWatch or Amazon Managed Service for Prometheus. With Amazon Managed Service for Prometheus, AWS expects these metrics:

        * `container_cpu_usage_seconds_total`
        * `container_memory_working_set_bytes`

        Follow the [AWS guide for split cost allocation with Amazon Managed Service for Prometheus](https://docs.aws.amazon.com/cur/latest/userguide/split-cost-allocation-data-resource-amp.html). AWS provides a managed collector option, but the cluster still needs collector access so metrics can flow from EKS to the managed Prometheus workspace.

        <Note>
          If you customize the scrape configuration, keep the `name`, `namespace`, and `pod` labels on the required metrics. AWS uses those labels to match usage metrics back to EKS workloads.
        </Note>
      </Tab>

      <Tab title="Kubecost or OpenCost">
        Use Kubecost or OpenCost when you need to split direct outbound network costs by workload.

        1. Install the Kubecost or OpenCost agent on each EKS cluster.
        2. Configure the agent to collect workload allocation data.
        3. Run a cron job that exports OpenCost data to a shared S3 bucket.
        4. Grant Costory access to that S3 bucket so the exported allocation data can be ingested.
      </Tab>
    </Tabs>
  </Step>

  <Step title="Add labels to pod deployments">
    Add labels that reflect ownership and purpose to each Kubernetes workload:

    ```yaml theme={null}
    metadata:
      labels:
        app: my-service
        team: platform
        env: production
    ```

    Use the same label keys across clusters. If teams already use different names, such as `owner`, `team`, and `cost_center`, keep them for now and merge them later in Costory.
  </Step>

  <Step title="Wait for data to flow into Costory">
    After configuring AWS <Tooltip href="/docs/glossary#split-cost-allocation">Split Cost Allocation</Tooltip>, **wait 2-3 days** for the data to appear in your Cost and Usage Report and flow into Costory.

    For Kubecost or OpenCost, the delay depends on your export schedule and the Costory ingestion cadence for the shared S3 bucket.
  </Step>

  <Step title="Validate labels in Costory">
    Before you build dashboards or <Tooltip href="/docs/glossary#chargeback">chargeback</Tooltip> views, check that your labels are present and populated:

    1. Open <Tooltip href="/docs/glossary#cost-explorer">Explorer</Tooltip>.
    2. Filter to your AWS account and EKS services.
    3. Group by one label, such as `team` or `app`.
    4. Check the `null` or unallocated bucket.
    5. Fix missing labels at the deployment level, then wait for the next billing export or OpenCost export.

    If labels are present under different names, merge them with <Tooltip href="/docs/glossary#dimensions">Dimensions</Tooltip>. For example, merge `k8s_label_team`, `team`, and `owner` into one reporting field.
  </Step>
</Steps>

## Analyze EKS costs in Costory

Once EKS labels appear in Costory, use them to find waste, build team reporting, and share cost changes.

<Tip>
  You can investigate EKS spend straight from chat with the [Costory MCP](/features/mcp). Ask "split last month's EKS cost by `team` and show the node pools with the highest waste ratio" and read the answer without opening Explorer.
</Tip>

### Find waste by node pool

Use <Tooltip href="/docs/glossary#cost-explorer">Explorer</Tooltip> to group by node pool and spot clusters with unusually high waste.

<img alt="Costory Explorer showing EKS waste ratio by node pool" />

*Explorer can show waste ratio by node pool so you can find over-provisioned cluster capacity.*

See the [Kubernetes waste guide](/use-cases/k8s_waste/visibility) for detailed waste analysis steps.

### Identify over-requesting deployments

For native split allocation, sort by requested CPU or memory to find workloads that reserve more capacity than they use.

<img alt="Costory Explorer showing EKS deployments with high requested CPU" />

*Deployment-level views help you find workloads that drive EKS waste through high resource requests.*

### Share recurring updates

Turn any saved view into a <Tooltip href="/docs/glossary#scheduled-report">Scheduled Report</Tooltip> and send it to your team.

<img alt="Costory Slack report showing EKS cost changes" />

*Cost Reports send saved EKS cost views to the teams that own the workloads.*

### Surface cost changes in Digest

Add your Kubernetes labels to the <Tooltip href="/docs/glossary#cost-breakdown-tree">Cost Breakdown Tree</Tooltip> so <Tooltip href="/docs/glossary#digest">Digest</Tooltip> highlights what changed.

<img alt="Costory Digest tree configured with EKS labels" />

*Digest can use EKS labels in its cost breakdown tree to explain workload-level cost changes.*

## Create a chargeback-ready EKS view

Use one saved view as the source of truth for team reporting:

1. Filter to container infrastructure costs, then group by the normalized team label.
2. Add a secondary group-by for `app`, `service`, or `namespace` so teams can see their main cost drivers.
3. Use [Contracted Cost](/docs/savings-plan-cost-fluctuation) when you want stable team-level reporting across Savings Plan movements.
4. Save the view with a name like `EKS chargeback by team`.
5. Schedule the view through [Cost Reports](/features/slack-reports) or add it to a [Dashboard](/features/dashboards).

For shared namespaces or platform services, create a <Tooltip href="/docs/glossary#virtual-dimensions">virtual dimension</Tooltip> that assigns the cost to the teams that consume the service.

## Next steps

<CardGroup>
  <Card title="Explore costs by cluster and label" href="/features/cost-explorer">
    Use <Tooltip href="/docs/glossary#cost-explorer">Explorer</Tooltip> to drill into EKS costs by cluster, namespace, and label.
  </Card>

  <Card title="Set up Cost Reports" href="/features/slack-reports">
    Turn saved views into a <Tooltip href="/docs/glossary#scheduled-report">Scheduled Report</Tooltip> and share weekly or monthly updates.
  </Card>

  <Card title="Configure monthly cost summaries" href="/features/digest">
    Tune the <Tooltip href="/docs/glossary#cost-breakdown-tree">Cost Breakdown Tree</Tooltip> so <Tooltip href="/docs/glossary#digest">Digest</Tooltip> highlights what changed.
  </Card>

  <Card title="Measure Kubernetes efficiency" href="/use-cases/k8s_waste/visibility">
    Quantify <Tooltip href="/docs/glossary#waste-ratio">waste ratio</Tooltip> and track over-provisioned clusters.
  </Card>
</CardGroup>

## FAQ

<AccordionGroup>
  <Accordion title="Do I need to install an agent on my cluster?">
    The option you choose determines agent requirements. AWS <Tooltip href="/docs/glossary#split-cost-allocation">Split Cost Allocation</Tooltip> does not require an agent in your cluster. AWS-managed usage metrics require a collector or agent to send metrics from the cluster. Kubecost and OpenCost require an agent on each cluster.
  </Accordion>

  <Accordion title="How long does it take for EKS data to show up in Costory?">
    Expect a 2-3 day delay after enabling <Tooltip href="/docs/glossary#split-cost-allocation">Split Cost Allocation</Tooltip> and activating <Tooltip href="/docs/glossary#cost-allocation-tags">Cost Allocation Tags</Tooltip>. The data must first appear in your <Tooltip href="/docs/glossary#cur">CUR</Tooltip>, then be ingested by Costory. For Kubecost or OpenCost, timing depends on the S3 export schedule.
  </Accordion>

  <Accordion title="What labels should I standardize for chargeback?">
    Start with `team`, `app` or `service`, and `env`. Standardizing these labels across clusters gives you consistent <Tooltip href="/docs/glossary#cost-allocation">cost allocation</Tooltip> and <Tooltip href="/docs/glossary#chargeback">chargeback</Tooltip> reporting.
  </Accordion>

  <Accordion title="Why do some workloads show up as unallocated?">
    Unallocated costs usually mean the pod or underlying resource does not have the label you are grouping by, or the label has not appeared in the <Tooltip href="/docs/glossary#cur">CUR</Tooltip> yet. Check the deployment labels, confirm the relevant <Tooltip href="/docs/glossary#cost-allocation-tags">Cost Allocation Tags</Tooltip> are active, then wait for the next export.
  </Accordion>

  <Accordion title="Should I allocate EKS costs by requests or actual usage?">
    Use requests when you want simple, stable allocation that reflects Kubernetes scheduling decisions. Use actual usage when you want allocation closer to what workloads consumed. Actual usage requires CloudWatch, Amazon Managed Service for Prometheus, or another usage data source.
  </Accordion>

  <Accordion title="How should I handle shared platform workloads?">
    Keep the original workload labels for investigation, then add a <Tooltip href="/docs/glossary#virtual-dimensions">virtual dimension</Tooltip> for reporting. For example, allocate observability, ingress, or CI runner costs to consuming teams based on namespace, service ownership, or another usage metric.
  </Accordion>
</AccordionGroup>


# Hourly Granularity for Bursty Workloads
Source: https://docs.costory.io/use-cases/hourly-cost-granularity

Use hourly cloud cost granularity to measure bursty workloads, price each event, and connect optimization work to per-event cost.

Hourly cloud cost granularity turns event-driven infrastructure into a measurable cost unit. This recipe shows how to price one bursty workload event, using BeReal's daily *Time to BeReal* notifications as the worked example.

<Info>
  Co-written with Thomas Lorreyte, Head of Infrastructure at BeReal.
</Info>

## When to use this recipe

Use hourly granularity when your infrastructure spend is driven by discrete events rather than steady-state traffic. The pattern shows up in workloads such as:

* Push notification fanouts, including BeReal's *Time to BeReal* notifications, marketing pushes, and scheduled email blasts.
* Scheduled batch jobs, such as nightly ETL, billing runs, periodic reconciliation, and ML training.
* Live event spikes, including sports streams, drop sales, product launches, and regional rollouts.
* Cron-driven workloads where you can name the recurring event that creates elastic cost.

<Tip>
  If you can name the discrete unit that drives most of your elastic cost, that unit deserves its own cost number.
</Tip>

## Why daily granularity falls short

Daily cost data is the default in many AWS, GCP, and Azure billing workflows. It works for steady workloads where today looks like yesterday. It breaks down when spend is concentrated into short windows.

Common failure modes:

1. Multiple events land on the same day. Three batch jobs on Monday and one on Tuesday make day-over-day comparison hard to interpret.
2. Events shift across time zones. Billing cutoffs are usually UTC or US Central, so a single calendar day can contain a different count of events depending on where they fired.
3. Spikes are short relative to the day. A 90-minute compute burst averaged into 24 hours can disappear into the daily total.

The consequence is practical: you cannot price one event in dollars, measure the ROI of optimization work, or scope a product decision that adds, moves, or removes one event.

<Note>
  Hourly granularity is part of the Copilot Plus tier. It is built for teams running bursty workloads where per-event cost matters. If your infrastructure is mostly steady-state, daily granularity in the base tier is usually enough.
</Note>

## The recipe

<Steps>
  <Step title="Name the event">
    Pick the discrete thing that drives your cost: a push notification, batch run, campaign send, or training job. Write down its rough duration and frequency.
  </Step>

  <Step title="Switch Explorer to hourly">
    In <Tooltip href="/docs/glossary#cost-explorer">Explorer</Tooltip>, set granularity to hourly and filter to the services that scale with the event. This is usually compute, and sometimes egress or storage I/O.
  </Step>

  <Step title="Anchor the event in time">
    Ingest your scale-up triggers as events through the [Events integration](/setup/events). Each spike is labeled and aligned with the cost curve, so the per-event window is clear.
  </Step>

  <Step title="Compute the per-event cost">
    Read the cost across the full event window: scale up, run, and scale down. Treat that window as one unit. Repeat across several events to calculate the mean and variance.
  </Step>

  <Step title="Operationalize the metric">
    Bring the per-event cost into recurring reporting. Engineering, product, and finance should read the same number when they discuss the workload.
  </Step>
</Steps>

## Worked example: BeReal

BeReal pushes four daily *Time to BeReal* notifications worldwide. Each one fires at a randomized time and opens a two-minute posting window. Infrastructure-wise, each notification is a clean, repeatable cost unit:

* Clusters scale up ahead of each notification.
* They handle the load through the posting window.
* They scale back down within the hour.

With daily aggregation, BeReal hit two specific problems:

* Variable count per day. The GCP billing cutoff is US Central. Depending on where notifications landed across time zones, a calendar day could contain three, four, or five notifications.
* No trustworthy per-notification number. The team had attempted a homemade hourly script, but the numbers were not solid enough to bring to product or finance.

With Costory's hourly granularity, the picture changed:

* Per-notification cost. A Japan notification costs X. A US notification costs Y. The numbers stay stable regardless of which calendar day they land on.
* Optimization ROI in dollars. Code changes on scale-up logic are measured against the next notification, not a noisy daily average. Wins and regressions both show up quickly.
* One view across teams. Product scopes new features against the same numbers finance uses to review the bill.
* Defensible scaling decisions. When infrastructure spend grows, the per-notification number shows whether the team is becoming more efficient or less efficient.

<Card title="Thomas Lorreyte, Head of Infrastructure at BeReal" icon="quote-left">
  "It was a drastic change from a product decision standpoint. We can now quantify, to the dollar, every optimization we ship on the moment infrastructure."
</Card>

## The decision it unlocked: a dedicated UK region

Western Europe shared one *Time to BeReal* notification. When it fires at 7pm in Paris, it lands at 6pm in London, past the window where engagement holds up. BeReal wanted to give the UK its own regional notification, but the decision sat blocked because the team could not size it. Adding a region means adding a notification, which means a new compute spike, and with daily granularity BeReal could not isolate the cost of a single notification. No cost number meant no ROI case, and on a small team product will not commit engineering time to a feature it cannot price.

<Card title="Thomas Lorreyte, Head of Infrastructure at BeReal" icon="quote-left">
  "We could have split the region before. We just couldn't say what it would cost, and on a small team, product won't sign off on a feature without an ROI number up front."
</Card>

Hourly granularity gave the team a credible per-notification cost. They estimated the marginal cost of the new UK notification, set it against the expected engagement lift of more posts and more ad inventory on the UK side, and turned a rough expectation into a defensible ROI. Product and finance signed off, and the dedicated UK region shipped in June 2026.

## Pair per-event cost with a business unit

Per-event cost answers what one event costs. Pairing it with a business unit, such as DAU, posts, impressions, processed records, or customers, turns it into <Tooltip href="/docs/glossary#unit-economics">unit economics</Tooltip> for the workload.

BeReal pairs per-notification cost with cost per DAU, split between:

* Static cost: storage of historical photos and baseline workloads.
* Elastic cost: the part that scales with traffic.

The combined metric supports day-to-day decisions:

* Engineering defends optimization work. Ship a scale-up change, measure the delta in dollars per DAU per notification, and report the result.
* Product scopes features against ROI. Price a new notification or cadence change against a credible cost-per-DAU-per-notification number, then weigh it against expected business lift.

See [Unit Economics](/automate-reporting/unit-economics) for the recurring metric workflow.

## Adapt it to your stack

Use these prompts to find the equivalent event in your infrastructure:

* Name the discrete event that drives most of your elastic cost.
* Define the full window: scale up, run, and scale down. Anything under 24 hours can benefit from hourly granularity.
* Pick the outcome that maps to one event, such as a post, an impression, a processed record, or a customer. One business unit per event is the cleanest pairing for ROI.
* Identify who needs the number. Engineering uses it to defend work, product uses it to scope features, and finance uses it to review the bill.

## Next steps

<CardGroup>
  <Card title="Explore hourly costs" icon="chart-simple" href="/features/cost-explorer">
    Switch Explorer to hourly granularity and inspect your spike shapes.
  </Card>

  <Card title="Ingest events" icon="calendar-days" href="/setup/events">
    Overlay scale-up triggers and workload events on the cost timeline.
  </Card>

  <Card title="Define unit economics" icon="calculator" href="/automate-reporting/unit-economics">
    Turn per-event cost into a per-user or per-outcome metric.
  </Card>

  <Card title="Correlate costs and events" icon="timeline" href="/features/events">
    Tie cost shifts back to the events that caused them.
  </Card>
</CardGroup>

## FAQ

<AccordionGroup>
  <Accordion title="Does hourly granularity make billing data real time?">
    No. Hourly granularity changes the time bucket in the billing data. AWS, GCP, and Azure exports still arrive with a delay, and Costory processes the data after it is available. See [Data Refresh](/docs/data-refresh) for provider freshness details.
  </Accordion>

  <Accordion title="Do I need events to use this recipe?">
    You can start with manual time windows, but events make the metric defensible. Once scale-up triggers are ingested, each spike is labeled on the cost curve and easier to compare over time.
  </Accordion>

  <Accordion title="What if my workload has multiple events in one day?">
    That is the main reason to use hourly granularity. Instead of explaining one daily total, split the day into event windows and calculate cost per event.
  </Accordion>
</AccordionGroup>


# Kubernetes Cost Visibility: Measure Waste, Allocate Costs, Reduce Over-Provisioning
Source: https://docs.costory.io/use-cases/k8s_waste/visibility

Kubernetes cost visibility for granular insight into waste, over-provisioned resources, and cost reallocation across teams

## Prerequisites

* You have a Kubernetes cluster running (AWS EKS or GCP GKE).
* You have a provider connected to Costory with your billing data ingested.
* You have labels / tags applied (or plan to apply them) to your pod deployments.

<Note>Azure AKS support is coming soon.</Note>

## Output

* Granular cost visibility at the Kubernetes label level (team, app, environment, etc.) without any third-party agent.
* Ability to track waste ratio per node pool and identify over-provisioned clusters.
* Foundation for cost allocation and chargeback across teams.

## How waste is defined in Kubernetes

In Kubernetes, your pods request a certain amount of CPU, memory, and GPU. The scheduler then decides on which node(s) to run your pods. Two concepts matter here:

* **Requests**: the amount of resources reserved by the pod. The scheduler uses this to pick the right node(s).
* **Limits**: the maximum resources a pod can consume before getting killed by the kernel (OOM killer).

Waste is the gap between available capacity and what pods have claimed:

```
waste = available_resources − requests
```

Waste does not take into account the limits of the pods. It's only based on the requests, since requests are used to schedule nodes, not limits.

### Example

Consider a cluster with two nodes and three pods:

|                     | CPU       | Memory   |
| ------------------- | --------- | -------- |
| Node 1 (available)  | 2 CPU     | 4 GB     |
| Node 2 (available)  | 4 CPU     | 4 GB     |
| **Total available** | **6 CPU** | **8 GB** |

|                     | CPU request | Memory request |
| ------------------- | ----------- | -------------- |
| Pod 1               | 1 CPU       | 2 GB           |
| Pod 2               | 1 CPU       | 2 GB           |
| Pod 3               | 1 CPU       | 1 GB           |
| **Total requested** | **3 CPU**   | **5 GB**       |

<img alt="Cluster overview" />

This gives us: **waste CPU = 6 − 3 = 3 CPU** and **waste memory = 8 − 5 = 3 GB**.

### Converting waste to cost

Since you pay per machine (not per core or per GB), we need a ratio to split the cost between CPU and memory. We use a **9:1 ratio** in favor of CPU. This reflects that, on most AWS and GCP instance families, CPU is roughly 9x more expensive per unit than memory. You can verify this by comparing on-demand pricing for common instance types.

From there, it's useful to compute waste at two levels:

* **Cluster level**: get an overall view of waste.
* **Node pool level**: if you rely on affinity rules, this helps identify which node pools are underutilized.

<Warning>
  Some providers compute waste from actual usage (possible in Costory via AWS
  Managed Prometheus). The downside is that per-namespace costs become unstable
  and harder to compare over time, since you pay for the nodes you schedule,
  not for what pods actually consume.
</Warning>

## Steps

<Steps>
  <Step title="Set up label visibility">
    <Tabs>
      <Tab title="AWS EKS">
        Follow the [EKS cost allocation](/use-cases/eks-cost-allocation) guide to enable split cost allocation and add labels to your pod deployments.
      </Tab>

      <Tab title="GCP GKE">
        On GKE, Google exposes cost allocation data with labels prefixed by `k8s_label_<label_name>` (see [GKE cost allocations](https://cloud.google.com/kubernetes-engine/docs/how-to/cost-allocations)). Your labels should be directly visible in Costory Dimensions, no extra setup needed.
      </Tab>
    </Tabs>
  </Step>

  <Step title="Break down costs by label">
    Once your pods have labels, such as team, app, and environment, use Costory **Dimensions** to merge these labels with your billing data. This lets you split cluster costs per label for cost allocation and chargeback.

    This allows you to fix the automatic renaming performed by GCP (`k8s_label_<label_name>`).
  </Step>

  <Step title="Monitor the waste over time">
    Track your waste ratio over time and get notified when it exceeds acceptable thresholds. In Costory, create an alert using the **Kubernetes Waste** template:

    <img alt="Create a Kubernetes Waste alert" />
  </Step>

  <Step title="Reallocate waste to teams">
    <Info>Waste reallocation is currently available for **EKS only**.</Info>

    Costory supports two reallocation strategies:

    | Strategy                             | How it works                                                                                                                                                                                  | Best for                                                                                                                                                     |
    | ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
    | **Namespace reallocation** (default) | Calculates per-hour usage requested by each namespace and reallocates waste proportionally.                                                                                                   | Most clusters with standard scheduling.                                                                                                                      |
    | **Node-based reallocation**          | Calculates per-hour resource requests per pod on each individual node and reallocates waste accordingly. A pod alone on a node will bear its full cost for the period it's the sole occupant. | Clusters relying heavily on affinity rules (node pools, zones, etc.) where a single pod may trigger a new node. Trade-off: more variance in waste over time. |

    By default, namespace reallocation is enabled. Reach out to us to enable node-based reallocation.
  </Step>
</Steps>

## What's next?

<Tip>
  Need a quick read on waste? Ask the [Costory MCP](/features/mcp) to "show the waste ratio per node pool this month and the namespaces driving the most over-provisioning" and get the answer in chat.
</Tip>

* Set up a [weekly Slack report](/features/slack-reports) to share waste metrics with your team.
* Add your Kubernetes labels to the [digest tree](/features/digest) for automated cost-change notifications.
* Explore your data in [Explorer](/features/cost-explorer) to identify faulty deployments over-requesting resources.


# LLM Cost Allocation: Track AI Spend by Team, Feature, and Customer
Source: https://docs.costory.io/use-cases/llm-ai-cost

Allocate and track LLM costs from Anthropic, OpenAI, Azure OpenAI, AWS Bedrock, GCP Vertex, and Mistral across teams and features. Learn cost per token attribution, showback, and chargeback strategies for shared API keys.

<Frame>
  <iframe title="LLM cost allocation walkthrough" />
</Frame>

You have one bill from your LLM provider. Your teams are on one shared API key. Nobody knows who spent what. This is the LLM cost allocation problem, and every team hits it the moment they start paying for AI. A single Anthropic or OpenAI bill reaches your CFO with no answer to the question: did search spend more than recommendations? Did the mobile team or backend team drive this spike? Without attribution at the time of consumption, chargeback becomes guesswork, and cost control becomes impossible.

Each LLM provider exposes attribution differently, and most offer only the bare minimum. Anthropic keys, OpenAI projects, Azure deployments, Bedrock IAM identities, Vertex labels, and Mistral workspaces are six different signals with six different levels of effort to wire up. This guide shows how to get **per-team cost data out of each LLM provider**, unify it in Costory, and build the allocation rules needed for showback, chargeback, and unit economics (cost per token, cost per customer, cost per feature).

The end state is a single dashboard that splits your AI spend by team, product, and model across every provider you connect, so every team sees their own cost contribution and the platform owns a complete view of AI economics.

## How each provider handles LLM cost allocation

There is no shared standard. Before plumbing anything, it helps to see the mechanism and the easiest practical split per provider.

| Provider               | Native attribution mechanism                                          | Easiest practical split            |
| ---------------------- | --------------------------------------------------------------------- | ---------------------------------- |
| Anthropic (Claude)     | One API key per app or team, plus the Cost API                        | API key per team                   |
| OpenAI                 | Projects, plus the Usage and Cost API (`group_by` project\_id, model) | One project (and key) per team     |
| Azure OpenAI / Foundry | Resource, deployment, and user-defined tags; `project` tag (preview)  | One deployment or tag per use case |
| AWS Bedrock            | Caller identity (IAM role or user) in the Cost and Usage Report       | One IAM role per team              |
| GCP Vertex AI          | Per-call metadata labels, or project-level labels                     | One GCP project per team           |
| Mistral                | Per-workspace billing, API keys scoped to a workspace                 | One workspace per team             |

Two patterns repeat across the table. Per-call labels (Vertex, partly Azure) give the finest granularity but are the most work to wire into every call site. Isolating usage into a separate account, project, key, or workspace per team is coarser but far easier to set up and maintain, and it is what most teams actually ship.

## What each provider exposes, and what Costory uses

Attribution starts at the provider. Each one exposes a different signal that ties spend to a team, key, project, or use case, with different granularity and effort. Below is the signal available from each provider and the field Costory ingests to build your per-team split. A developer could wire any of this up internally; what Costory adds is knowing the right field for each provider and keeping the mapping current as keys, projects, and deployments change.

### Anthropic (Claude)

**Available:** Anthropic ties usage to the **API key** and actor (user email or key name), exposed through the [Cost and Usage API](https://docs.anthropic.com/en/api/admin-api/usage-cost/get-cost-report). Using one API key per app, team, or environment puts the split in the billing data with no code.

**In Costory:** pick the [Anthropic connector that matches where you pay](/setup/billing/anthropic#which-connector-to-use). **Anthropic Claude Code** (Claude Console) ingests the key or actor as **Sub account id** and **Resource name**, and the model as **Service name**. **Anthropic Claude AI** (claude.ai Enterprise) ingests per-user cost from the Analytics API. If you call Claude through Amazon Bedrock instead of the Anthropic API, that spend lands via the [AWS connector](/setup/billing/aws) (billed as `Claude ... (Amazon Bedrock Edition)`).

### OpenAI

**Available:** OpenAI ties usage to **projects**, readable through the [Usage and Cost API](https://developers.openai.com/cookbook/examples/completions_usage_api) with `group_by` on `project_id`, `line_item`, and `model`. One project (and project key) per team gives isolation and per-project budget caps. For finer per-feature attribution, OpenAI's guidance is to log application metadata (feature, route, customer) alongside `response.usage` at call time, since the export carries no per-call labels.

**In Costory:** the [OpenAI connector](/setup/billing/openai) ingests organization costs from the Costs API. Project, API key, and user identifiers come through when you grant **API keys + Projects** read. GPT consumed through Azure still lands via the [Azure connector](/setup/billing/azure) as Azure OpenAI (Cognitive Services) charges, split by deployment and region.

### Azure OpenAI / Foundry

**Available:** Azure has the richest native model. Costs carry **resource**, **deployment**, and **user-defined tags**, you can group cost by model deployment, and Microsoft added [project-level chargeback (preview)](https://learn.microsoft.com/en-us/azure/foundry/concepts/manage-costs) that auto-tags every Foundry project. Naming a deployment per use case (one for support, one for document processing) makes deployment-level cost equal to cost per feature.

**In Costory:** the [Azure connector](/setup/billing/azure) ingests Azure Cost Management data, including Azure OpenAI (billed under Cognitive Services). Costory detects the deployment and user-defined tags as [dimensions](/features/tagging/dimensions) for the team or use-case split.

### AWS Bedrock

**Available:** Bedrock has no per-call labels. Instead, AWS records the **caller identity** (IAM role or user) on every Bedrock line in the Cost and Usage Report. Per the [AWS guide](https://aws.amazon.com/blogs/aws-cloud-financial-management/track-amazon-bedrock-costs-by-caller-identity-with-iam-based-cost-allocation/), you tag your IAM principals, activate those cost allocation tags, and enable caller-identity allocation in a CUR 2.0 export, which adds a `line_item_iam_principal` column. It breaks when calls route through a shared gateway role, and AWS sub-accounts per team are a heavier alternative than a GCP project.

**In Costory:** the [AWS connector](/setup/billing/aws) ingests the CUR including `line_item_iam_principal` and your cost allocation tags, so once the export option is on, the per-team split flows in automatically.

### GCP Vertex AI

**Available:** Vertex recently added [custom metadata labels on each API call](https://docs.cloud.google.com/gemini-enterprise-agent-platform/models/capabilities/add-labels-to-api-calls#google-models), the most granular option, though wiring a label into every call through the Python SDK is work to roll out and keep consistent. The simpler path, used by a Costory customer, is one GCP project per team.

**In Costory:** the [GCP connector](/setup/billing/gcp) ingests the project and all resource labels from the billing export, so either approach maps onto a team dimension.

### Mistral

**Available:** Mistral [bills per workspace](https://docs.mistral.ai/admin/user-management-finops/billing) and scopes API keys to a workspace, with per-workspace usage and spending caps in the admin panel. The natural unit is one workspace per team or environment.

**In Costory:** Mistral is most often run through AWS Bedrock or Azure, and that spend reaches Costory via the [AWS](/setup/billing/aws) and [Azure](/setup/billing/azure) connectors (publisher Mistral AI). Mistral's direct platform is not a native connector today.

## Implementation examples per provider

### Anthropic: API key per team

Create separate API keys in the Anthropic console, one per team. Name them for clarity (the name shows in billing):

```bash theme={null}
# In Anthropic console, create keys named by team
- search-team-key
- recommendations-team-key
- backend-team-key

# Then use the right key in your application
export ANTHROPIC_API_KEY=search-team-key
```

Each key's usage appears separately in the [Cost and Usage API](https://docs.anthropic.com/en/api/admin-api/usage-cost/get-cost-report), and Costory ingests the key name as **Resource name**.

### OpenAI: one project per team

Create a project per team in the OpenAI Platform, then connect Costory with a read-only [Admin API key](/setup/billing/openai). Costory ingests organization costs from the Costs API. With **API keys + Projects** read, project and key names show instead of raw ids.

### Azure OpenAI: Deployment names and resource tags

Create separate deployments per team or feature. The deployment name itself is part of the URL and automatically appears in billing. Follow Azure's [cost management guidance](https://learn.microsoft.com/en-us/azure/foundry/concepts/manage-costs) to tag and allocate:

Create deployments in Azure:

```bash theme={null}
# Azure Portal → Azure OpenAI → Deployments
# Name them by team or feature
- search-gpt4
- recommendations-gpt35
- backend-gpt4
```

Tag the resource in Azure:

```bash theme={null}
az cognitiveservices account update \
  --resource-group my-rg \
  --name my-openai \
  --tags team=search environment=production feature=ai-search
```

API call (the deployment name routes the cost):

```bash theme={null}
curl https://my-openai.openai.azure.com/openai/deployments/search-gpt4/chat/completions \
  -H "api-key: $AZURE_OPENAI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [{"role": "user", "content": "What is AI?"}],
    "model": "gpt-4-turbo"
  }'
```

The deployment name (`search-gpt4`) automatically tags the cost in Azure billing. Resource-level tags (team, environment) appear in Cost Management. Costory ingests the deployment name and tags as dimensions for team-level allocation.

### AWS Bedrock: Separate IAM roles per team

Create one IAM role per team. Each application assumes its team's role to call Bedrock. AWS records which role made the call:

Create separate roles:

```bash theme={null}
# Each role allows bedrock:InvokeModel
# Role 1: SearchTeamBedrockRole (for search application)
# Role 2: RecommendationsTeamBedrockRole (for recommendations)
```

Tag each role to identify the owner:

```bash theme={null}
aws iam tag-role \
  --role-name SearchTeamBedrockRole \
  --tags Key=team,Value=search Key=environment,Value=production

aws iam tag-role \
  --role-name RecommendationsTeamBedrockRole \
  --tags Key=team,Value=recommendations Key=environment,Value=production
```

In your application, assume the right role and call Bedrock:

```python theme={null}
import boto3

# Search service assumes SearchTeamBedrockRole
sts = boto3.client('sts')
credentials = sts.assume_role(
    RoleArn='arn:aws:iam::ACCOUNT:role/SearchTeamBedrockRole',
    RoleSessionName='search-session'
)

# Use temporary credentials to call Bedrock
bedrock = boto3.client(
    'bedrock-runtime',
    aws_access_key_id=credentials['Credentials']['AccessKeyId'],
    aws_secret_access_key=credentials['Credentials']['SecretAccessKey'],
    aws_session_token=credentials['Credentials']['SessionToken']
)

response = bedrock.invoke_model(
    modelId='anthropic.claude-opus-v1',
    body=json.dumps({"prompt": "..."})
)
```

Enable caller-identity allocation in your CUR 2.0 export. AWS then records the IAM role ARN (`line_item_iam_principal`) for every Bedrock call. Costory ingests the ARN and its tags to allocate costs by team.

### GCP Vertex AI: Per-call metadata labels

Pass labels on every API call. This is the most granular approach:

```python theme={null}
import vertexai
from vertexai.generative_models import GenerativeModel

vertexai.init(project="my-project", location="us-central1")
model = GenerativeModel("gemini-2.0-flash")

response = model.generate_content(
    "What is AI?",
    # Labels passed per-call
    labels={
        "team": "search",
        "feature": "ai-search",
        "customer": "acme",
        "environment": "production"
    }
)
```

Or use the REST API:

```bash theme={null}
curl https://us-central1-aiplatform.googleapis.com/v1/projects/my-project/locations/us-central1/endpoints/gemini:streamGenerateContent \
  -H "Authorization: Bearer $GCLOUD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": {...},
    "labels": {
      "team": "search",
      "feature": "ai-search",
      "customer": "acme"
    }
  }'
```

These labels appear in Vertex billing exports and Costory ingests them as dimensions. Alternatively, use one GCP project per team (simpler but coarser).

### Mistral: Workspace per team

Create a workspace in Mistral for each team. Each workspace has its own billing and API keys:

```bash theme={null}
# Organization → Workspaces → Create workspace
# Name: "search-team", "recommendations-team"
# Each workspace gets unique API keys scoped to it

export MISTRAL_API_KEY=search_team_key  # Only works in search-team workspace
```

Workspace-level billing appears in the Mistral admin console. Costory ingests the workspace ID to split costs.

## Track and allocate LLM costs across providers in Costory

Each provider hands you a different key: an API key, a project, a deployment, an IAM principal, a label, or a workspace. On their own they live in separate billing consoles. You can stitch them together yourself by exporting each provider's cost data, normalizing it, and maintaining the mapping in your own warehouse, but that is a pipeline to build and own. It is easier and more reliable to do it in Costory.

Costory has native [billing connectors](/setup/billing) for **Anthropic, OpenAI, AWS, Azure, and GCP** and normalizes them into one schema. From there, you build a single [virtual dimension](/features/tagging/dimensions) (call it `team`, `product`, or `customer`) with one rule per source that maps its native key to the right owner. This unified view becomes your source of truth for chargeback and cost per token attribution.

| Source (Costory connector)     | Native key Costory ingests           | Allocate by                |
| ------------------------------ | ------------------------------------ | -------------------------- |
| Anthropic                      | Sub account id (API key / actor)     | rule per key               |
| OpenAI                         | project (and API key when present)   | rule per project           |
| Azure OpenAI (Azure connector) | deployment or user-defined tag       | rule per deployment or tag |
| AWS Bedrock (AWS connector)    | IAM principal or cost allocation tag | rule per role              |
| GCP Vertex (GCP connector)     | project or label                     | rule per project           |

The result is one `team` axis spanning every connected source. Spend re-allocates automatically as new keys, projects, or deployments appear, with no manual updates, and the same dimension feeds chargeback, budgets, and reports.

<Note>
  In practice, many teams consume these models through the clouds: GPT through Azure OpenAI, Claude and Mistral through Bedrock or Azure. That spend already flows into Costory through the AWS, Azure, and GCP connectors, with the cloud's own attribution (deployment, IAM principal, project, label). Direct OpenAI Platform usage has a [native connector](/setup/billing/openai). Mistral's direct platform is not a native connector yet; track it with the provider methods above, or [contact us](mailto:contact@costory.io) about your setup.
</Note>

## Build the cross-provider dashboard with the MCP

Once the data is unified, you do not have to assemble the dashboard by hand. Connect the [Costory MCP](/features/mcp) to Claude, Cursor, or any MCP client and ask for it in plain language:

> "Build a dashboard of our LLM cost across all connected AI sources (Anthropic, OpenAI, Azure OpenAI, Bedrock, Vertex). Total cost over time by provider, a breakdown by model, and a split by team using our team dimension."

The assistant works out the scope across providers, builds the widgets, and saves the [dashboard](/features/dashboards) for you to review and adjust. You can keep asking for the cuts you need ("split the Bedrock cost by IAM principal", "compare this month to last by team") and it runs them without you rebuilding queries.

## What LLM cost management looks like once spend is allocated

With one cross-provider, team-level view in place, the AI bill becomes something you can manage and report on:

<CardGroup>
  <Card title="Measure adoption" icon="chart-line" href="/features/unit-economics">
    Track which teams and products use AI most, and how fast usage is growing. Rising spend is usually adoption, and now you can show it per team.
  </Card>

  <Card title="Budget per team" icon="money-check-dollar" href="/use-cases/automate_budget">
    Set an AI budget on the team dimension and track burn against it.
  </Card>

  <Card title="Alert on spend" icon="bell" href="/features/alerts">
    Fire a Slack or email alert when a team's daily AI cost crosses a threshold, before month-end.
  </Card>
</CardGroup>

## FAQ

<AccordionGroup>
  <Accordion title="How do you allocate OpenAI or Anthropic costs across teams?">
    Each LLM provider offers a native mechanism: OpenAI uses projects and the Costs API. Anthropic uses API keys and the Cost and Usage API. The simplest approach is one API key (Anthropic) or project (OpenAI) per team. This isolation puts the split directly in the billing data. Connect those sources with the [OpenAI](/setup/billing/openai) and [Anthropic](/setup/billing/anthropic) connectors, then map projects and keys onto a team virtual dimension.
  </Accordion>

  <Accordion title="What is LLM cost allocation and why does it matter?">
    LLM cost allocation is the process of assigning shared AI spend to the teams, products, or customers that generated it. Your LLM provider sends one bill, but multiple teams consume from one API key or account. Without allocation, each team sees only the total company spend, not their contribution. Allocation enables chargeback (billing teams for their usage), budget enforcement (per-team cost caps), and accurate unit economics (cost per token, cost per customer). Costory automates this by ingesting each provider's billing data and applying your allocation rules across all sources at once.
  </Accordion>

  <Accordion title="How do you track LLM costs by team?">
    Track LLM costs by team by isolating each team's usage into its own provider signal, then reading it back from billing: one Anthropic API key, one OpenAI project, one Azure deployment, one Bedrock IAM role, or one Vertex label per team. Each provider stamps the team onto its own billing lines, so the split lands in the data with no per-call code. Costory ingests all of these into a single `team` dimension, so you track spend by team across every connected provider in one view instead of stitching consoles together.
  </Accordion>

  <Accordion title="What is the difference between showback and chargeback?">
    Showback is visibility: teams see their own costs in a dashboard or report, but no bill is exchanged. Chargeback is billing: each team receives an internal invoice for their share of the AI bill based on allocation rules. Showback is a prerequisite for chargeback and helps teams make cost-conscious decisions even without internal billing. Both require cost allocation; chargeback is a stronger accountability mechanism.
  </Accordion>

  <Accordion title="How do you calculate cost per token for each team?">
    Cost per token combines billing data (total cost per provider and model) with usage data (token counts). Most LLM providers expose token counts in their billing API or usage dashboard. Divide your team's total cost by their total tokens consumed to get cost per token. This metric shows which teams are getting the most efficiency from their AI spending and helps identify runaway prompts or inefficient model usage. Track this in Costory by building a formula that divides your cost query by a usage metric from your provider's telemetry.
  </Accordion>

  <Accordion title="What happens with shared API key allocation when one team spikes?">
    If all teams share one API key, you cannot see which team drove a spike at the provider level. You must rely on per-call instrumentation: logging which team made each request in your application, then correlating that log with usage. Costory's <Tooltip href="/docs/glossary#dimensions">virtual dimensions</Tooltip> support this by ingesting both provider billing (the total cost) and your application logs (which team made the call), then allocating the cost forward. The alternative is to isolate each team into a separate API key or project at the provider level, which eliminates ambiguity but requires more infrastructure.
  </Accordion>

  <Accordion title="Can you split per-customer AI cost?">
    Yes. Per-customer attribution follows the same pattern as per-team. If you have one API key shared across customers, instrument your API calls to log customer ID, then ingest those logs into Costory as a usage metric or custom dimension. Map that customer data to your billing costs. Costory then allocates the AI bill by customer, enabling per-customer unit economics (cost per customer request, cost per customer feature). This is especially important for platforms or SaaS products where AI is part of the offering you charge for.
  </Accordion>
</AccordionGroup>

## Next steps

* Connect each provider from [Billing Data](/setup/billing).
* Build your cross-provider allocation [virtual dimension](/features/tagging/dimensions).
* Use the [Costory MCP](/features/mcp) to build and investigate your AI cost in natural language.


# Overview
Source: https://docs.costory.io/use-cases/overview

Explore practical guides to get the most out of Costory

## Explore

Discover where your money goes: get granular cost visibility across services and platforms.

<CardGroup>
  <Card title="Allocate LLM cost per team" icon="robot" href="/use-cases/llm-ai-cost">
    Get team-labeled cost data from Anthropic, OpenAI, Azure, Bedrock, Vertex, and Mistral, then unify it in one cross-provider dashboard.
  </Card>

  <Card title="Hourly cost granularity" icon="clock" href="/use-cases/hourly-cost-granularity">
    Measure bursty workloads by pricing each notification, batch job, or event.
  </Card>

  <Card title="EKS cost allocation" icon="aws" href="/use-cases/eks-cost-allocation">
    Get granular visibility on your EKS cluster costs using AWS native cost allocation tags.
  </Card>

  <Card title="Measuring Kubernetes cost" icon="dharmachakra" href="/use-cases/k8s_waste/visibility">
    Understand Kubernetes waste, over-provisioned resources, and cost allocation across teams.
  </Card>

  <Card title="BigQuery cost visibility with dbt" icon="magnifying-glass-chart" href="/use-cases/dbt_bigquery_visibility/increase_visibility">
    Track and allocate BigQuery costs at the dbt model level using labels.
  </Card>
</CardGroup>

## Annotate

Enrich, allocate, and restructure your cost data to reflect how your organization actually works.

<CardGroup>
  <Card title="Reallocate API costs" icon="arrow-right-arrow-left" href="/use-cases/reallocate_api_costs">
    Split shared API costs across teams using an external usage metric like API call counts.
  </Card>

  <Card title="Shared cost allocation of a Cloud SQL database" icon="database" href="/use-cases/allocate_shared_cloud_sql_database/allocate">
    Split a shared Cloud SQL database cost across consuming teams based on actual usage.
  </Card>

  <Card title="Automated env allocation" icon="layer-group" href="/use-cases/automated_env_allocation/visibility">
    Allocate your costs per environment using all the metadata available in your billing data.
  </Card>
</CardGroup>

## Analyze

Build metrics, track unit economics, and derive actionable insights from your cost data.

<CardGroup>
  <Card title="Unit economics using Amplitude" icon="chart-line" href="/use-cases/amplitude/cost_per_active_users">
    Monitor your cost in comparison to the active users of your app.
  </Card>

  <Card title="Track unit economics" icon="chart-mixed" href="/automate-reporting/unit-economics">
    Link cloud cost increases to business growth with unit economics formulas.
  </Card>
</CardGroup>

## Share

Communicate costs to the right stakeholders with budgets, reports, and tailored metrics.

<CardGroup>
  <Card title="Automate your cloud budget" icon="money-check-dollar" href="/use-cases/automate_budget">
    Define and share cloud budgets per team, set alerts, and keep teams accountable.
  </Card>

  <Card title="Cost metrics per persona" icon="users" href="/use-cases/show_the_correct_cost_metric_to_each_persona">
    Share the correct cost metric with each persona: tech, finance, and accounting.
  </Card>

  <Card title="FinOps metrics for exec team" icon="briefcase" href="/use-cases/what_your_exec_team_wants/value">
    Show the correct metrics to your executive team.
  </Card>

  <Card title="Monthly cost reporting" icon="calendar" href="/automate-reporting/monthly-reviews">
    Automate monthly cloud cost reports with AI-powered summaries and root-cause analysis.
  </Card>

  <Card title="Decentralize FinOps" icon="users-gear" href="/automate-reporting/decentralize-finops">
    Deliver scoped cost reports to each team via Slack, Teams, or email.
  </Card>
</CardGroup>


# Split Shared API Costs Across Teams Using Usage Metrics
Source: https://docs.costory.io/use-cases/reallocate_api_costs

Allocate untagged or shared API costs to the right teams based on actual usage data. This guide walks you through usage-based shared cost allocation with Costory, from connecting an external metric to building a reusable chargeback model.

When part of your cloud bill is untagged, for example a shared API gateway used by several teams, tags alone can't attribute it. Without <Tooltip href="/docs/glossary#cost-allocation">cost allocation</Tooltip>, those costs land in an "other" bucket, and chargeback or showback becomes impossible.

This guide splits shared API costs proportionally. You connect an external usage metric (API call counts per team) in Costory, then build a reusable <Tooltip href="/docs/glossary#virtual-dimensions">virtual dimension</Tooltip> that attributes the right share of cost to each team going forward.

## Prerequisites

* You have identified the total cost of this API in your billing data.
* You have a usage metric from your internal monitoring tool (e.g., API call counts per team) that can serve as an allocation key to split costs across callers.

In this example, you will use an AWS S3 Parquet file that looks like:

| date                | team    | region | api\_call\_count |
| :------------------ | :------ | :----- | ---------------: |
| 2025-12-01 00:00:00 | Team\_A | North  |             1081 |
| 2025-12-01 00:00:00 | Team\_A | South  |             1330 |
| 2025-12-01 00:00:00 | Team\_A | East   |             1201 |
| 2025-12-01 00:00:00 | Team\_A | West   |              505 |
| 2025-12-01 00:00:00 | Team\_B | North  |              983 |

For each team and region, you know how many API calls were made.

<Tip>
  This use case uses an AWS S3 Parquet file, but you can use any source on the [External metric](/setup/usage-metrics) grid: Datadog, Datadog CI Visibility, Amplitude, BigQuery, Google Sheets, Tsuga, CloudWatch, or S3.
</Tip>

## What you get: per-team cost attribution

* A per-team cost view based on actual API usage, ready for chargeback or showback.
* A reusable <Tooltip href="/docs/glossary#virtual-dimensions">virtual dimension</Tooltip> that automatically allocates the shared cost going forward, with no manual updates needed.

## How it works

The overall flow is: export a usage metric from your monitoring system, import it into Costory, preview the proportional split, then lock it in with a Virtual Dimension.

```mermaid theme={null}
graph LR
    A["Usage metric (S3 Parquet)"] --> B["Costory Metric"]
    B --> C["Explorer preview"]
    C --> D["Virtual Dimension"]
    D --> E["Per-team cost view"]
```

## How to split shared API costs step by step

<Steps>
  <Step title="Create a bucket and share access with Costory">
    <Accordion title="Terraform / Manual setup">
      <Tabs>
        <Tab title="Terraform">
          ```hcl theme={null}
          terraform {
            required_providers {
              aws = {
                source  = "hashicorp/aws"
                version = ">= 5.0"
              }
              costory = {
                source  = "costory-io/costory"
                version = ">= 0.1.0"
              }
            }
          }

          variable "costory_token" {
            type        = string
            description = "Costory API token."
            sensitive   = true
          }

          variable "s3_name" {
            type        = string
            description = "Base name for the S3 bucket."
            default     = "costory-allocation-data"
          }

          provider "aws" {
          }

          provider "costory" {
            token = var.costory_token
          }

          data "aws_caller_identity" "current" {}
          data "costory_service_account" "current" {}

          locals {
            account_id  = data.aws_caller_identity.current.account_id
            bucket_name = "${var.s3_name}-${local.account_id}"
          }

          # --- S3 bucket ---

          resource "aws_s3_bucket" "allocation" {
            bucket = local.bucket_name
          }

          resource "aws_s3_bucket_public_access_block" "allocation" {
            bucket = aws_s3_bucket.allocation.id

            block_public_acls       = true
            block_public_policy     = true
            ignore_public_acls      = true
            restrict_public_buckets = true
          }

          # --- IAM policy: allow read on the bucket ---

          data "aws_iam_policy_document" "read_s3" {
            statement {
              sid    = "AllowReadAllocation"
              effect = "Allow"

              actions = [
                "s3:ListBucket",
                "s3:GetObject",
              ]

              resources = [
                aws_s3_bucket.allocation.arn,
                "${aws_s3_bucket.allocation.arn}/*",
              ]
            }
          }

          resource "aws_iam_policy" "read_s3" {
            name        = "costory-read-s3-${var.s3_name}"
            description = "Allows Costory to read the allocation S3 bucket."
            policy      = data.aws_iam_policy_document.read_s3.json
          }

          data "aws_iam_policy_document" "federated_assume" {
            statement {
              effect  = "Allow"
              actions = ["sts:AssumeRoleWithWebIdentity"]

              principals {
                type        = "Federated"
                identifiers = ["accounts.google.com"]
              }

              condition {
                test     = "StringEquals"
                variable = "accounts.google.com:sub"
                values   = data.costory_service_account.current.sub_ids
              }
            }
          }

          resource "aws_iam_role" "federated" {
            name               = "costory-trust-link-${var.s3_name}"
            assume_role_policy = data.aws_iam_policy_document.federated_assume.json
          }

          resource "aws_iam_role_policy_attachment" "read_s3" {
            role       = aws_iam_role.federated.name
            policy_arn = aws_iam_policy.read_s3.arn
          }
          ```
        </Tab>

        <Tab title="Manual">
          1. Create an S3 bucket
          2. Create an IAM role with READ and LIST permissions on this bucket
          3. Add a federated trust policy so the Costory service account can assume the role
          4. Attach the read policy to the role
        </Tab>
      </Tabs>
    </Accordion>
  </Step>

  <Step title="Schedule the metric export">
    Create a scheduled job (cron, Airflow, GitHub Actions, or any orchestrator) that writes the metric file to the bucket every day. The job should:

    * **Output format**: A Parquet file with one row per combination of dimensions per day. At minimum, include a `date` column, one or more dimension columns (e.g., `team`, `region`), and a numeric value column (e.g., `api_call_count`).
    * **S3 prefix**: Write files under a consistent prefix, for example `s3://<bucket>/api_cost_allocations/`. Costory scans this prefix for new files.
    * **Overwrite strategy**: You can safely write a new file each day. Costory applies an incremental overwrite strategy: for a given day, the last data received wins, and existing data for other days is preserved.

    <Tip>
      You can force a re-import on demand from the Metrics DataSource page. Otherwise, files are imported automatically every day at 06:00 UTC.
    </Tip>
  </Step>

  <Step title="Create the metric in Costory">
    <Tabs>
      <Tab title="Terraform">
        ```hcl theme={null}
        # Add this to the same Terraform configuration as the previous step.
        resource "costory_metrics_datasource_s3_parquet" "single_dims" {
          name        = "API Usage"
          bucket_name = local.bucket_name
          prefix      = "api_cost_allocations"
          role_arn    = aws_iam_role.federated.arn

          metrics_definition = [
            {
              metric_name  = "API Usage"
              gap_filling  = "ZERO" // How to handle missing values for a day
              aggregation  = "SUM" // How to aggregate the metric across multiple days
              value_column = "api_call_count"
              date_column  = "date"
              dimensions   = ["region", "team"]
              unit         = "calls"
            }
          ]
        }
        ```
      </Tab>

      <Tab title="Manual">
        1. Go to the Metrics DataSource Page and create a new metric.
        2. Select the S3 bucket and the file name.
        3. Select the column that contains the date.
        4. Select the column that contains the team.
        5. Select the column that contains the region.
        6. Select the column that contains the API call count.
        7. Save the metric.
      </Tab>
    </Tabs>

    <Check>The metric will take a few minutes to be ingested. Once ready, you can see it and its values in Costory.</Check>

    <Frame>
      <img alt="Metrics Datasources page with the API Usage metric listed and marked Active" />
    </Frame>
  </Step>

  <Step title="Preview the reallocation">
    Use [Explorer](/features/cost-explorer) to preview how the reallocated costs would look before committing to a virtual dimension.

    The idea is to build a formula that computes each team's proportional share of the total API cost:

    | Row   | What it represents                    | Example                                |
    | ----- | ------------------------------------- | -------------------------------------- |
    | **a** | API Usage metric, grouped by team     | Team A: 4 117 calls, Team B: 983 calls |
    | **b** | Total API usage across all teams      | 5 100 calls                            |
    | **c** | The reallocation formula: `a / b * d` | Team A gets 80.7% of the cost          |
    | **d** | Total cost of the shared API resource | \$1 000                                |

    The formula `a / b * d` gives you: **(team's calls / total calls) \* total cost = team's share**.

    <Frame>
      <img alt="Explorer with four rows building a proportional cost reallocation formula" />
    </Frame>
  </Step>

  <Step title="Create the Virtual Dimension">
    Create a [virtual dimension](/features/tagging/dimensions#virtual-dimensions) that automatically allocates the shared cost going forward.

    * Add a new rule for those API costs:
      * Rely on reallocation based on usage metrics
      * Use the metric you just imported
      * Choose an allocation strategy:
        * Identity mapping: The new label value is the team name
        * Regex mapping: The API name contains the team name (extract it with a regex)
        * Manual mapping: The API name has no relation to the team name; map each name manually
    * Save the virtual dimension

    Watch how a Virtual Dimension rule is configured with dynamic allocation based on the imported usage metric:

    <Frame>
      <img alt="Walkthrough of creating a Virtual Dimension with dynamic allocation based on usage metrics" />
    </Frame>
  </Step>
</Steps>

## Next steps: automate and share

<Tip>
  Prefer to skip the UI? The [Costory MCP](/features/mcp) can draft, preview, and publish this reallocation virtual dimension from chat. Try "draft a virtual dimension that splits my API gateway cost across teams using the API Usage metric, then show me the preview."
</Tip>

* Set up a [weekly Slack report](/features/slack-reports) to share the reallocated costs with each team automatically.
* Explore the results in [Explorer](/features/cost-explorer) to validate cost attribution per team.
* Build on this allocation to create a [budget tracking](/use-cases/automate_budget) workflow per team.


# Share the correct cost for each persona
Source: https://docs.costory.io/use-cases/show_the_correct_cost_metric_to_each_persona

Learn how to share the correct cost for each persona

## What you will get:

* You will know what cost metric to use with each persona.
* A dashboard for your finance team.
* A dashboard for your accounting team.
* Set default metrics for each persona.
* Show the correct savings thanks to your work using reservations / savings plans.

## Prerequisites:

* You know how to split your bill between Production and R\&D costs.
* You choose a metric to follow your product usage: daily active users, total number of customers, total revenue...
* You choose a metric to follow your R\&D costs: total number of engineers, time spend on the CI per repository...

## Steps

### Step 1: Match a metric to each persona

* **Tech team**: usage-based or amortized cost. Hide credits, savings plans, and reservations (savings plans have a caveat, see Step 2). Daily or hourly granularity.
* **Accounting team**: amortized cost, so AWS upfront costs are spread over time. Daily or hourly granularity.
* **Finance team**: billed cost, the cash paid each month. Monthly granularity.

### Step 2: Handle reservations and savings plans

A global savings plan spread across accounts can move between accounts over time, which creates fake cost swings per account. Contracted Cost is the cost without the savings plan but with your EDP, so it stays stable against those movements. To catch savings plan under-use or over-use, create an alert.

### Step 3: Set a default metric per persona

Create a [team](/features/teams) per persona (for tech, one team per actual team). Set a default metric for each team so Explorer and dashboards use it automatically. See [Teams](/features/teams) for setup.

### Step 4: Start from Costory templates

Start from the pre-built dashboard templates and customize one per persona. See [Dashboards](/features/dashboards) for the available templates.

## Related

* [Cost Metrics](/docs/cost-metrics) for a full comparison of each metric and how it handles credits and discounts.
* [Savings Plan discount sharing issues](/docs/savings-plan-cost-fluctuation) to understand why Contracted Cost is more stable.
* [Teams](/features/teams) for setting default metrics per team.
* [FinOps metrics for exec team](/use-cases/what_your_exec_team_wants/value) for building executive-level reports.


# Show the correct metrics to your exec team
Source: https://docs.costory.io/use-cases/what_your_exec_team_wants/value

Learn how to show the correct metrics to your exec team

## Prerequisites:

1. You know how to split your bill between Production and R\&D costs.
2. You choose a metric to follow your product usage: daily active users, total number of customers, total revenue...
3. You choose a metric to follow your R\&D costs: total number of engineers, time spend on the CI per repository...

## Output:

* A clear report or dashboard to share with your exec team.

## Steps:

<Steps>
  <Step title="Step 1: Split your bill">
    Split your bill between Production and R\&D / marketplace purchases costs:

    a. If you have a correct cost labeling strategy in place, directly rely on your labels

    b. Create a virtual dimension to correctly split the cost: Prod / Non Prod.

    <Note>
      Rule of thumb: if you delete this cost line and the product stops working, it
      is a Prod cost. If the product keeps working, it is likely a Non Prod cost.
    </Note>
  </Step>

  <Step title="Step 2: Choose the metrics">
    | Your business                 | Potential Metric to follow          | What source to ingest it into Costory ?                        |
    | ----------------------------- | ----------------------------------- | -------------------------------------------------------------- |
    | B2C business varying on usage | Daily active users                  | Datadog, Amplitude, BigQuery etc.                              |
    | B2C business varying on usage | Number of email sent                | Datadog, BigQuery etc.                                         |
    | B2B / B2C                     | Total revenue                       | GoogleSheet using Zapier for automation, BigQuery              |
    | B2B / B2C                     | Number of customers                 | GoogleSheet using Zapier for automation / S3 export / BigQuery |
    | R\&D costs                    | Total number of engineers           | GoogleSheets / BigQuery                                        |
    | R\&D costs                    | Time spend on the CI per repository | Datadog CI Visibility                                          |
  </Step>

  <Step title="Step 3: Set targets">
    <Info>
      A number alone says little. Is 0.1€ per active user per month good, or a sign the business is in trouble? Share the targets you want to hit and the reasoning with your exec team. They often already know what is sustainable and should weigh in.
    </Info>

    * In advanced Explorer, look at how the marginal cost moves over time. Does it track your business objectives?
    * Set a target with a min and max boundary. Below which marginal cost do you prioritize cost growth, and above which do you prioritize cost reduction?
  </Step>

  <Step title="Step 4: Create a report">
    The report MUST contains:

    * The total cost of the production environment this month and YTD.
    * The marginal cost of the production environment this month and YTD based on the metric above.

    <Info>
      The marginal cost value itself does not always mean much. What is important is the trend and the evolution of this marginal cost.
    </Info>

    * The total cost of the non production environment this month and YTD.
    * The marginal cost of the non production environment this month and YTD based on the metric above.
    * The total of credits received from the CSP for the current Year.
    * The savings achieved thanks to your work using reservations / savings plans.
    * If part of the cost is not attributed to a team / feature: show how much it is and its variation.

    <Warning>
      Never share a dashboard without context.
    </Warning>

    What additional information could you add to the report?

    * The decomposition of the cost per team / feature if available.
    * If a cost reduction is achieved / a spike happened: the why behind it.
    * If you're using Costory: you can choose a set of events to include in the report: this will help you understand the why behind the cost changes.
  </Step>
</Steps>


# Cost Reports
Source: https://docs.costory.io/v2/Automate/reports

Schedule recurring cloud cost reports to Slack, Microsoft Teams, or email from a dashboard, widget, or Explorer view, in the UI, from chat, or via the API.

Cost dashboards only work if people see them. **Cost Reports** deliver multi-cloud cost breakdowns directly to Slack, Microsoft Teams, or email on a recurring schedule.

<Frame>
  <img alt="Costory report editor showing monthly cost by environment with schedule and email delivery settings" />
</Frame>

## Overview

Cost Reports deliver a dashboard, dashboard widget, or Explorer-backed cost view as a formatted snapshot on a schedule you define. Each report includes the cost breakdown, a comparison against a previous period, and a direct link back to Costory.

Where it fits in your day-to-day:

* Sending weekly cost updates to each squad's Slack channel so engineers see their infrastructure spend without logging into a dashboard
* Delivering monthly executive summaries to leadership with pre-filtered views scoped to their business unit
* Keeping SRE and platform teams informed about infrastructure cost trends as part of their existing review cadence

## Get started

<Tip>
  You can schedule a report from chat. Ask the [Costory MCP](/features/mcp) to *"send a weekly cost-by-team report to our #finops Slack channel"* and it creates the schedule against the view you describe.
</Tip>

<Steps>
  <Step title="Create or open the source view">
    Open the [dashboard](/features/dashboards), dashboard widget, or [Explorer](/features/cost-explorer) query you want to deliver on a schedule.
  </Step>

  <Step title="Click Schedule Report">
    Open the action menu and select **Schedule Report**. This opens the scheduling
    configuration panel.

    <Frame>
      <img alt="Configuring a scheduled cost report in Costory from the Explorer, including chart, cadence, and destinations" />
    </Frame>
  </Step>

  <Step title="Choose a delivery channel">
    Select where the report should be delivered. Costory supports Slack,
    Microsoft Teams, and email.

    <Info>
      You can create multiple scheduled reports from the same source view, each
      targeting a different channel or cadence.
    </Info>

    <Info>
      Before first delivery, complete channel setup for
      [Slack](/setup/collaboration/slack), [Microsoft
      Teams](/setup/collaboration/teams), or
      [Email](/setup/collaboration/email).
    </Info>
  </Step>

  <Step title="Configure cadence and comparison">
    Set the delivery schedule and the comparison period for the report.

    <ResponseField name="Cadence" type="weekly | monthly">
      How often the report is generated and delivered.
    </ResponseField>

    <ResponseField name="Comparison Period">
      The reference period shown alongside the current period, so recipients see
      the cost change at a glance.
    </ResponseField>
  </Step>

  <Step title="Confirm and send a test report">
    Review the configuration and click **Save**. You can send a test report
    immediately to verify the channel, format, and data before the first
    scheduled delivery.
  </Step>
</Steps>

<Check title="Scheduled Reports are free" icon="check">
  There is no additional cost for scheduling reports. Send as many as you need
  across Slack, Teams, and email.
</Check>

## How a report is built

Every report combines the same building blocks, whether you assemble them in the UI, describe them to the [Costory MCP](/features/mcp), or send them to the [Reports API](/api-reference/reports/overview):

* A **scope**: the accounts, services, tags, or filters the report covers.
* A **group-by**: the dimension the cost is split by, such as service, environment, or vendor.
* One or more **widgets**: the charts rendered in the message.
* A **cadence**: weekly on a set weekday, monthly, or on-demand.
* One or more **destinations**: the Slack, Teams, or email targets it fans out to.

Each widget carries its own Explorer query in `advancedExplorerRequest`: a `period`, and a `queries` array holding the metric, group-by, and chart type to render.

| Widget                     | What it shows                                                           |
| -------------------------- | ----------------------------------------------------------------------- |
| Trend graph                | Cost over time as a line, so recipients see direction and relative size |
| Top and bottom             | The largest items, and optionally the biggest increases and decreases   |
| [Digest](/features/digest) | A breakdown of the change into drivers, with an optional AI narrative   |
| Dashboard PDF              | A full dashboard rendered as an attached PDF                            |
| Text                       | A short markdown note to frame the numbers                              |

## What you can build

The building blocks above cover a wide range of reports. The examples below show the output, the sentence that creates it through the Costory MCP, and the equivalent [Reports API](/api-reference/reports/create-a-report) call.

| Report                                                          | Grouped by                | Cadence           | Sent to            |
| --------------------------------------------------------------- | ------------------------- | ----------------- | ------------------ |
| [Weekly engineering pulse](#weekly-engineering-pulse)           | Environment, then service | Weekly            | Team Slack channel |
| [Executive environment costs](#executive-environment-costs)     | Environment               | Monthly           | Leadership email   |
| [Kubernetes namespace showback](#kubernetes-namespace-showback) | Namespace                 | Weekly            | Platform channel   |
| [Marketplace and vendor spend](#marketplace-and-vendor-spend)   | Vendor (invoice issuer)   | Monthly           | Finance channel    |
| [Credit and discount runway](#credit-and-discount-runway)       | Charge category           | Monthly           | FinOps channel     |
| [Tag coverage](#tag-coverage)                                   | Service                   | Weekly or monthly | FinOps channel     |

<Info>
  Each API example carries a complete widget query in `advancedExplorerRequest`.
  Scope filters go in each query's `whereClause`; the examples show the intended
  filter as a comment. See [Create a
  report](/api-reference/reports/create-a-report) for the full schema, the list
  of metrics and date presets, and a live playground.
</Info>

### Weekly engineering pulse

Give each engineering team a weekly view of what moved. Group by environment, then by service, turn on the Digest AI narrative, and deliver it to the team's channel every Monday. Engineers see which service drove the change and why, without opening a dashboard. See the [Decentralize FinOps guide](/automate-reporting/decentralize-finops) for a full walkthrough.

<Frame>
  <img alt="Weekly Costory report grouped by environment and service with a Digest AI summary in Slack" />
</Frame>

<CodeGroup>
  ```text Ask Costory (MCP) theme={null}
  Send a weekly report every Monday to #eng-costs, grouped by
  environment and then service, with the Digest AI summary turned on.
  ```

  ```json API theme={null}
  POST /reports
  {
    "name": "Weekly engineering pulse",
    "scheduledPeriod": "WEEKLY",
    "scheduledWeekday": 1,
    "context": { "groupBy": "env", "datePreset": "LAST_WEEK" },
    "widgets": [
      {
        "type": "DIGEST",
        "enableAiInvestigation": true,
        "additionalGroupBy": ["cos_service_name"],
        "advancedExplorerRequest": {
          "period": { "datePreset": "LAST_WEEK", "aggBy": "Week" },
          "queries": [
            {
              "type": "cost",
              "metricId": "cost",
              "aggregator": "SUM",
              "groupBy": "env",
              "whereClause": {},
              "name": "Cost",
              "colorIndex": 0,
              "chartType": "TABLE"
            }
          ],
          "eventsFilter": {},
          "bookmarkedEvents": []
        }
      }
    ],
    "destinations": [
      { "destinationType": "SLACK", "destinationValue": "C0ENGCOSTS" }
    ]
  }
  ```
</CodeGroup>

### Executive environment costs

Leadership usually wants one clean number per environment, not a drill-down. Build an environment <Tooltip href="/docs/glossary#virtual-dimensions">Virtual Dimension</Tooltip> that maps accounts, tags, and cluster labels to prod, staging, and dev, then schedule a monthly ranking of the top environments. Add a twelve-month trend to catch non-production creep, and deliver it to a leadership channel or mailing list. See [Executive Cost Reports](/use-cases/what_your_exec_team_wants/value) for more on building views for stakeholders.

<Frame>
  <img alt="Monthly Costory report ranking cost by environment with a twelve-month trend line" />
</Frame>

<CodeGroup>
  ```text Ask Costory (MCP) theme={null}
  Every month, email leadership@acme.com a report of our top
  environments by cost, with a twelve-month trend.
  ```

  ```json API theme={null}
  POST /reports
  {
    "name": "Environment costs",
    "scheduledPeriod": "MONTHLY",
    "context": { "groupBy": "env", "datePreset": "LAST_MONTH" },
    "widgets": [
      {
        "type": "TOP_FLOP",
        "topN": 10,
        "flopN": 0,
        "advancedExplorerRequest": {
          "period": { "datePreset": "LAST_MONTH", "aggBy": "Period" },
          "queries": [
            {
              "type": "cost",
              "metricId": "cost",
              "aggregator": "SUM",
              "groupBy": "env",
              "whereClause": {},
              "name": "Cost by environment",
              "colorIndex": 0,
              "chartType": "BAR"
            }
          ],
          "eventsFilter": {},
          "bookmarkedEvents": []
        }
      },
      {
        "type": "GRAPH_SNAPSHOT",
        "advancedExplorerRequest": {
          "period": { "datePreset": "LAST_12_MONTHS", "aggBy": "Month" },
          "queries": [
            {
              "type": "cost",
              "metricId": "cost",
              "aggregator": "SUM",
              "groupBy": "env",
              "whereClause": {},
              "name": "Cost by environment",
              "colorIndex": 0,
              "chartType": "LINE"
            }
          ],
          "eventsFilter": {},
          "bookmarkedEvents": []
        }
      }
    ],
    "destinations": [
      { "destinationType": "EMAIL", "destinationValue": "leadership@acme.com" }
    ]
  }
  ```
</CodeGroup>

### Kubernetes namespace showback

On shared clusters it is hard to tell which team drives the EKS or GKE bill. Scope a report to reallocated namespace cost, group by namespace, and send a weekly breakdown with a fourteen-week trend and the last week's movers to the platform channel. This gives each team <Tooltip href="/docs/glossary#showback">showback</Tooltip> on shared infrastructure. A sudden drop is as useful as a spike, since it can mean a broken workload or a real saving.

<Frame>
  <img alt="Weekly Costory report of reallocated Kubernetes namespace cost with trend and movers" />
</Frame>

<CodeGroup>
  ```text Ask Costory (MCP) theme={null}
  Send a weekly namespace cost report to #platform every Monday,
  with a fourteen-week trend and the top and bottom movers.
  ```

  ```jsonc API theme={null}
  POST /reports
  {
    "name": "Namespace showback",
    "scheduledPeriod": "WEEKLY",
    "scheduledWeekday": 1,
    "context": { "groupBy": "cos_namespace_reallocated", "datePreset": "LAST_WEEK" },
    "widgets": [
      {
        "type": "GRAPH_SNAPSHOT",
        "advancedExplorerRequest": {
          "period": { "datePreset": "TRAILING_14_WEEKS", "aggBy": "Week" },
          "queries": [
            {
              "type": "cost",
              "metricId": "cost",
              "aggregator": "SUM",
              "groupBy": "cos_namespace_reallocated",
              "whereClause": {}, // scope: only rows with a reallocated namespace (cos_namespace_reallocated != null)
              "name": "Cost by namespace",
              "colorIndex": 0,
              "chartType": "LINE"
            }
          ],
          "eventsFilter": {},
          "bookmarkedEvents": []
        }
      },
      {
        "type": "TOP_FLOP",
        "topN": 10,
        "flopN": 10,
        "advancedExplorerRequest": {
          "period": { "datePreset": "LAST_WEEK", "aggBy": "Period" },
          "queries": [
            {
              "type": "cost",
              "metricId": "cost",
              "aggregator": "SUM",
              "groupBy": "cos_namespace_reallocated",
              "whereClause": {}, // scope: only rows with a reallocated namespace (cos_namespace_reallocated != null)
              "name": "Cost by namespace",
              "colorIndex": 0,
              "chartType": "BAR"
            }
          ],
          "eventsFilter": {},
          "bookmarkedEvents": []
        }
      }
    ],
    "destinations": [
      { "destinationType": "SLACK", "destinationValue": "C0PLATFORM" }
    ]
  }
  ```
</CodeGroup>

### Marketplace and vendor spend

Finance often needs to reconcile third-party software billed through the cloud invoice against purchase orders and renewals. Scope a report to marketplace purchases, group by vendor (the invoice issuer), and deliver a monthly ranking with a twelve-month trend to the finance or procurement channel. Native usage such as compute never enters the chart, so the vendor list stays clean.

<Frame>
  <img alt="Monthly Costory report of AWS Marketplace spend grouped by vendor with a trend line" />
</Frame>

<CodeGroup>
  ```text Ask Costory (MCP) theme={null}
  Each month, send a marketplace-only report grouped by vendor
  to #finance, with a twelve-month trend.
  ```

  ```jsonc API theme={null}
  POST /reports
  {
    "name": "Marketplace spend by vendor",
    "scheduledPeriod": "MONTHLY",
    "context": { "groupBy": "cos_invoice_issuer", "datePreset": "LAST_MONTH" },
    "widgets": [
      {
        "type": "GRAPH_SNAPSHOT",
        "advancedExplorerRequest": {
          "period": { "datePreset": "LAST_12_MONTHS", "aggBy": "Month" },
          "queries": [
            {
              "type": "cost",
              "metricId": "cost",
              "aggregator": "SUM",
              "groupBy": "cos_invoice_issuer",
              "whereClause": {}, // scope: marketplace purchases only (cos_marketplace_purchase == true)
              "name": "Marketplace cost by vendor",
              "colorIndex": 0,
              "chartType": "LINE"
            }
          ],
          "eventsFilter": {},
          "bookmarkedEvents": []
        }
      },
      {
        "type": "TOP_FLOP",
        "topN": 10,
        "flopN": 0,
        "advancedExplorerRequest": {
          "period": { "datePreset": "LAST_MONTH", "aggBy": "Period" },
          "queries": [
            {
              "type": "cost",
              "metricId": "cost",
              "aggregator": "SUM",
              "groupBy": "cos_invoice_issuer",
              "whereClause": {}, // scope: marketplace purchases only (cos_marketplace_purchase == true)
              "name": "Marketplace cost by vendor",
              "colorIndex": 0,
              "chartType": "BAR"
            }
          ],
          "eventsFilter": {},
          "bookmarkedEvents": []
        }
      }
    ],
    "destinations": [
      { "destinationType": "SLACK", "destinationValue": "C0FINANCE" }
    ]
  }
  ```
</CodeGroup>

### Credit and discount runway

Committed-use discounts, savings plans, and promotional credits all settle on the monthly invoice, and a shrinking credit line is easy to miss until it is gone. Group a report by charge category to separate usage from credits, discounts, and refunds, and schedule it monthly. The last-month movers surface a credit that is running out before the real invoice arrives.

<Frame>
  <img alt="Monthly Costory report grouped by charge category showing credits and discounts over time" />
</Frame>

<CodeGroup>
  ```text Ask Costory (MCP) theme={null}
  Send a monthly report grouped by charge category to #finops so
  we can watch our credits and discounts.
  ```

  ```json API theme={null}
  POST /reports
  {
    "name": "Credit and discount runway",
    "scheduledPeriod": "MONTHLY",
    "context": { "groupBy": "cos_charge_category", "datePreset": "LAST_MONTH" },
    "widgets": [
      {
        "type": "GRAPH_SNAPSHOT",
        "advancedExplorerRequest": {
          "period": { "datePreset": "LAST_12_MONTHS", "aggBy": "Month" },
          "queries": [
            {
              "type": "cost",
              "metricId": "cost",
              "aggregator": "SUM",
              "groupBy": "cos_charge_category",
              "whereClause": {},
              "name": "Cost by charge category",
              "colorIndex": 0,
              "chartType": "LINE"
            }
          ],
          "eventsFilter": {},
          "bookmarkedEvents": []
        }
      },
      {
        "type": "TOP_FLOP",
        "topN": 10,
        "flopN": 10,
        "advancedExplorerRequest": {
          "period": { "datePreset": "LAST_MONTH", "aggBy": "Period" },
          "queries": [
            {
              "type": "cost",
              "metricId": "cost",
              "aggregator": "SUM",
              "groupBy": "cos_charge_category",
              "whereClause": {},
              "name": "Cost by charge category",
              "colorIndex": 0,
              "chartType": "BAR"
            }
          ],
          "eventsFilter": {},
          "bookmarkedEvents": []
        }
      }
    ],
    "destinations": [
      { "destinationType": "SLACK", "destinationValue": "C0FINOPS" }
    ]
  }
  ```
</CodeGroup>

### Tag coverage

When half the bill cannot be allocated, a tagging campaign needs a number the team can move. Track the share of in-scope cost that carries the required tag, grouped by service so the gaps point at an owner. The coverage ratio is a formula over two cost queries: tagged cost divided by all in-scope cost. Schedule it weekly during an active cleanup, then drop to monthly once coverage holds.

<Frame>
  <img alt="Weekly Costory report showing the share of cost tagged with team, broken down by service" />
</Frame>

<CodeGroup>
  ```text Ask Costory (MCP) theme={null}
  Send a weekly report to #finops showing the share of cost tagged
  with team, broken down by service, and the services with the most
  untagged spend.
  ```

  ```jsonc API theme={null}
  POST /reports
  {
    "name": "Tag coverage",
    "scheduledPeriod": "WEEKLY",
    "scheduledWeekday": 1,
    "context": { "groupBy": "cos_service_name", "datePreset": "LAST_MONTH" },
    "widgets": [
      {
        "type": "GRAPH_SNAPSHOT",
        "advancedExplorerRequest": {
          "period": { "datePreset": "TRAILING_14_WEEKS", "aggBy": "Week" },
          "queries": [
            {
              "type": "cost",
              "alias": "a",
              "metricId": "cost",
              "aggregator": "SUM",
              "groupBy": "cos_service_name",
              "whereClause": {}, // scope: rows carrying the required tag (team != null)
              "visible": false,
              "name": "Tagged cost",
              "colorIndex": 0,
              "chartType": "LINE"
            },
            {
              "type": "cost",
              "alias": "b",
              "metricId": "cost",
              "aggregator": "SUM",
              "groupBy": "cos_service_name",
              "whereClause": {},
              "visible": false,
              "name": "All cost",
              "colorIndex": 1,
              "chartType": "LINE"
            },
            {
              "type": "formula",
              "formula": "a / b",
              "name": "Tag coverage",
              "colorIndex": 2,
              "chartType": "LINE"
            }
          ],
          "eventsFilter": {},
          "bookmarkedEvents": []
        }
      }
    ],
    "destinations": [
      { "destinationType": "SLACK", "destinationValue": "C0FINOPS" }
    ]
  }
  ```
</CodeGroup>

### Explain a cost change on demand

Not every report is recurring. Before a finance review, you often need to explain a single number that moved. Send an on-demand report with a Digest widget that decomposes the change into drivers, for example compute in production up and a new database service added. Set the cadence to none and trigger it once with [Run a report now](/api-reference/reports/run-a-report-now).

<CodeGroup>
  ```text Ask Costory (MCP) theme={null}
  Explain why our bill went up last month, broken down by service,
  and post it to #finance once.
  ```

  ```json API theme={null}
  POST /reports
  {
    "name": "Why did the bill move?",
    "scheduledPeriod": null,
    "context": { "groupBy": "cos_service_name", "datePreset": "LAST_MONTH" },
    "widgets": [
      {
        "type": "DIGEST",
        "enableAiInvestigation": true,
        "advancedExplorerRequest": {
          "period": { "datePreset": "LAST_MONTH", "aggBy": "Period" },
          "queries": [
            {
              "type": "cost",
              "metricId": "cost",
              "aggregator": "SUM",
              "groupBy": "cos_service_name",
              "whereClause": {},
              "name": "Cost by service",
              "colorIndex": 0,
              "chartType": "TABLE"
            }
          ],
          "eventsFilter": {},
          "bookmarkedEvents": []
        }
      }
    ],
    "destinations": [
      { "destinationType": "SLACK", "destinationValue": "C0FINANCE" }
    ]
  }
  ```
</CodeGroup>

## Build reports with the API

Everything above is available over HTTP through the [Reports API](/api-reference/reports/overview). Authenticate with a bearer token as described in the [API overview](/api-reference/overview), then [create a report](/api-reference/reports/create-a-report) in a single call, [preview a widget](/api-reference/reports/preview-a-report-widget) before scheduling, or [run one now](/api-reference/reports/run-a-report-now). The Costory MCP and the UI both call the same endpoints, so a report built in chat can be edited by hand later, and the other way around.

<Warning>
  The reports endpoints are currently a **staging preview** on
  `https://app-staging-api.costory.io` and are not yet on the production API.
  Point integrations at staging until they ship to production.
</Warning>

## Frequently Asked Questions

<AccordionGroup>
  <Accordion title="Which delivery channels does Costory support?">
    Costory supports Slack, Microsoft Teams, and email. You can send the same
    report to multiple channels by creating separate schedules from the same
    source view.
  </Accordion>

  <Accordion title="Can I send different views to different channels?">
    Yes. Each scheduled report is tied to a specific dashboard, widget, or Explorer context. You can create as
    many source views as you need and schedule each one to a different channel with its own cadence.
  </Accordion>

  <Accordion title="How often can reports be sent?">
    Reports can be sent weekly or monthly. The cadence is configured per
    schedule, so one source view can have a weekly report going to the engineering
    channel and a monthly report going to leadership.
  </Accordion>

  <Accordion title="Can I create reports from chat or the API?">
    Yes. Ask the [Costory MCP](/features/mcp) in plain language, or call the
    [Reports API](/api-reference/reports/overview) directly. Both resolve to the
    same `POST /reports` call, so a report you start in chat can be edited in the
    UI or updated over the API.
  </Accordion>

  <Accordion title="What's the difference between Cost Reports and Digest?">
    A [Cost digest](/features/digest) is one report element type, alongside
    Graph, Top / Flop, Dashboard PDF, and Text. Digests build a multi-level cost
    tree, apply change thresholds, and can attach an AI narrative for Slack,
    email, and in-app Summary, Tree, or Table views. Other elements cover charts,
    rankings, dashboard PDFs, and markdown notes in the same scheduled report.
  </Accordion>

  <Accordion title="Is there a limit on the number of scheduled reports?">
    No. Scheduled reports are included at no additional cost, and there is no
    cap on the number of active schedules.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup>
  <Card title="Reports API" icon="code" href="/api-reference/reports/overview">
    Create, schedule, and run reports over HTTP
  </Card>

  <Card title="Dashboards" icon="chart-pie" href="/features/dashboards">
    Build persistent cost dashboards with multiple widgets
  </Card>

  <Card title="Explorer" icon="magnifying-glass" href="/features/cost-explorer">
    Build the query context behind a report
  </Card>

  <Card title="Digest" icon="bolt" href="/features/digest">
    Auto-triage cost anomalies with AI-generated incident reports
  </Card>

  <Card title="Decentralize FinOps" icon="sitemap" href="/automate-reporting/decentralize-finops">
    Give each squad ownership of their cloud costs
  </Card>

  <Card title="Automate Cloud Budgets" icon="money-bill-trend-up" href="/use-cases/automate_budget">
    Define per-team budgets and automate alerts when teams exceed targets
  </Card>

  <Card title="Executive Cost Reports" icon="chart-line" href="/use-cases/what_your_exec_team_wants/value">
    Build the dashboards your leadership team wants to see
  </Card>
</CardGroup>