Introduction - CostGraph Documentation

The CostGraph API is the API the CostGraph app itself uses. Everything you can see in the app, such as spend, insights, budgets, alert destinations, and members, you can read or manage with it. The base URL is https://api.costgraph.ai. Requests and responses are JSON, except where an endpoint returns a file.

Authentication

The API accepts two kinds of credentials:

Credential	Header	Use it for
API key	`X-API-Key: <key>`	Scripts, CI, and integrations that read spend
Access token	`Authorization: Bearer <token>`	A signed-in person, or an app acting for one through Sign in with CostGraph within the permissions they approved

Create API keys under Settings > API keys. A key carries scopes: give it focus:read to read cost, forecast, commitments, unit economics, and allocation coverage. Endpoints that manage your organization, such as budgets, alert destinations, and single sign-on, need a signed-in person with the matching role. API keys and app tokens can’t call them.

Tenant

Endpoints under /api/v1/tenant/ work on one tenant. Send its ID in the X-CostGraph-Tenant-ID header. Endpoints under /api/v1/organizations/{org_id}/ work on the whole organization.

Periods and filters

Cost endpoints share the same parameters:

period: month_to_date (the default), last_7d, last_30d, calendar_month with month=YYYY-MM, or custom with start and end.
filter: repeated key:value filters, such as filter=provider:aws or filter=tag:team:platform. Repeat a key to match any of its values.
layer: billed for your bills, allocation for Kubernetes allocation, or ci for CI spend.

Example

curl "https://api.costgraph.ai/api/v1/tenant/cost/query?group_by=provider&period=last_30d" \
  -H "X-API-Key: $COSTGRAPH_API_KEY" \
  -H "X-CostGraph-Tenant-ID: $TENANT_ID"

​Authentication

​Tenant

​Periods and filters

​Example

Authentication

Tenant

Periods and filters

Example