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

1
{
2
  "merge_hosted_spend": 194.0,
3
  "byok_spend": 3.24,
4
  "web_search_spend": 0.01,
5
  "total_spend": 197.25,
6
  "request_count": 1204,
7
  "model_spend": {
8
    "anthropic/claude-opus-4-8": 122.0,
9
    "openai/gpt-5.5": 72.0
10
  },
11
  "model_spend_granularity": "month",
12
  "projects": [
13
    { "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 }
14
  ],
15
  "start": "2026-07-01",
16
  "end": "2026-07-31"
17
}

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

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

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