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

# Introduction

> Read your spend and manage your CostGraph organization over HTTP

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](/costgraph/developers/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

```shell theme={null}
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"
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.