Usage

Two endpoints report spend, both taking start and end (YYYY-MM-DD, inclusive; default is the current month) and requiring the read_usage scope. Spend fields are USD: merge_hosted_spend is managed-credential spend, byok_spend is BYOK usage at list price, and web_search_spend covers server-side web search.

Totals are day-granular for any range. model_spend (and the vendor breakdown) aggregate by calendar month, covering the months your range overlaps, hence model_spend_granularity: "month" in responses.

Organization rollup

GET /v1/organization/usage returns org totals plus a per-model breakdown. Add group_by=project, group_by=api_key, or group_by=vendor for a per-dimension breakdown.

curl "https://api-gateway.merge.dev/v1/organization/usage?start=2026-07-01&end=2026-07-31&group_by=project" \
  -H "Authorization: Bearer mgmt_<your_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"
}

Project usage

GET /v1/projects/{project_id}/usage returns the same day-granular totals scoped to one project, plus the project’s per-model breakdown.

curl "https://api-gateway.merge.dev/v1/projects/{project_id}/usage?start=2026-07-01&end=2026-07-31" \
  -H "Authorization: Bearer mgmt_<your_management_key>"

{
  "project_id": "7c6d5e4f-3a2b-4c1d-8e9f-0a1b2c3d4e5f",
  "merge_hosted_spend": 120.0,
  "byok_spend": 0.75,
  "web_search_spend": 0.0,
  "total_spend": 120.75,
  "request_count": 800,
  "model_spend": {
    "openai/gpt-5.5": 98.0,
    "anthropic/claude-opus-4-8": 22.75
  },
  "model_spend_granularity": "month",
  "start": "2026-07-01",
  "end": "2026-07-31"
}

Project model_spend accrues from when per-project model tracking was deployed; months before that report totals with an empty map.