> This page is for Gateway.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.merge.dev/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.merge.dev/_mcp/server.

# Usage

> Read spend over /v1/organization/usage and /v1/projects/{project_id}/usage: date ranges, managed vs BYOK vs web search spend, per-model breakdowns, and group_by dimensions.

Two endpoints report organization or single-project spend for a date range, for your own dashboards, chargeback reports, or alerts.

## Reference

| Endpoint                              | Scope                               | Adds                                                   |
| ------------------------------------- | ----------------------------------- | ------------------------------------------------------ |
| `GET /v1/organization/usage`          | `view_billing`                      | Optional `group_by`: `project`, `api_key`, or `vendor` |
| `GET /v1/projects/{project_id}/usage` | `view_billing` or `manage_projects` | `project_id` in the response                           |

Both take inclusive `YYYY-MM-DD` `start` and `end` dates, defaulting to the current month through today. A range over 366 days, `start` after `end`, or a malformed date returns `400`.

| Response field                 | Meaning                                                                                                    |
| ------------------------------ | ---------------------------------------------------------------------------------------------------------- |
| `merge_hosted_spend`           | Spend on Merge-managed vendor keys, in USD                                                                 |
| `byok_spend`                   | BYOK usage priced at list price                                                                            |
| `web_search_spend`             | Server-side web search                                                                                     |
| `total_spend`, `request_count` | Totals for the exact date range                                                                            |
| `model_spend`                  | `{model: spend}` for every calendar month the range overlaps, so `model_spend_granularity` is `"month"`    |
| `projects`                     | With `group_by=project`: a list of `{project_id, ...spend fields}`, highest spend first                    |
| `api_keys`                     | With `group_by=api_key`: a list of `{api_key_id, ...spend fields}`, where `api_key_id` is the key's `hash` |
| `vendors`                      | With `group_by=vendor`: `{vendor: spend}`, month-granular like `model_spend`                               |

Project `model_spend` is empty for months before per-project model tracking began; totals are still reported.

## Read spend

**`Organization by project`**

```bash title="Organization by project"
curl "https://api-gateway.merge.dev/v1/organization/usage?start=2026-07-01&end=2026-07-31&group_by=project" \
  -H "Authorization: Bearer $MERGE_GATEWAY_MANAGEMENT_KEY"
```

**`One project`**

```bash title="One project"
curl "https://api-gateway.merge.dev/v1/projects/$PROJECT_ID/usage?start=2026-07-01&end=2026-07-31" \
  -H "Authorization: Bearer $MERGE_GATEWAY_MANAGEMENT_KEY"
```

```json
{
  "merge_hosted_spend": 194.0,
  "byok_spend": 3.24,
  "web_search_spend": 0.01,
  "total_spend": 197.25,
  "request_count": 1204,
  "model_spend": {
    "anthropic/claude-opus-4-8": 122.0,
    "openai/gpt-5.5": 72.0
  },
  "model_spend_granularity": "month",
  "projects": [
    { "project_id": "7c6d5e4f-3a2b-4c1d-8e9f-0a1b2c3d4e5f", "merge_hosted_spend": 120.0, "byok_spend": 0.0, "web_search_spend": 0.0, "total_spend": 120.0, "request_count": 800 }
  ],
  "start": "2026-07-01",
  "end": "2026-07-31"
}
```

## Next steps

#### [Cost governance and savings](/merge-gateway/cost/cost-governance-and-savings)

See the same spend in the dashboard

#### [Budgets](/merge-gateway/automation/projects-api/budgets)

Cap a project's spend

#### [Management API reference](/merge-gateway/management-api)

Full response schemas