Usage

Read organization and project spend with per-model breakdowns

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

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"

{
  "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

See the same spend in the dashboard

Budgets

Cap a project’s spend

Management API reference

Full response schemas