---
title: "Get usage data"
method: GET
path: "/usage"
tags: ["Usage"]
---

# Get usage data

`GET /usage`

Returns customer-scoped usage aggregates. Supports filtering by time range, chain, API key, grouping, and granularity. By default returns summary and balance.

## Query parameters

- `from` string, date-time
- `to` string, date-time
- `include` string
- `group_by` string
- `granularity` 'day' | 'hour'
- `chain_id` string
- `api_key_id` integer
- `limit` integer

## Response `200`

Usage data

- UsageResponse
  - `customer_id` integer, required
  - `period` UsagePeriod, required
    - `from` string, date-time, required
    - `to` string, date-time, required
  - `summary` UsageSummary
    - `credits_consumed` number, required — Total credits spent in the period.
    - `request_count` integer, required — Total number of requests.
    - `credits_per_request` number, required — Average cost per request.
  - `balance` UsageBalance
    - `credits` number, required — Current credit balance.
    - `as_of` string, date-time, required — Timestamp of the balance snapshot.
  - `by_chain` UsageByChain[] — Per-chain breakdown.
    - `chain_id` string, required
    - `credits_consumed` number, required
    - `request_count` integer, required
  - `by_api_key` UsageByAPIKey[] — Per-API-key breakdown.
    - `api_key_id` integer, required
    - `name` string, nullable
    - `key_hint` string, required — Masked API key (e.g. rm_a…456).
    - `credits_consumed` number, required
    - `request_count` integer, required
  - `by_api_key_chain` UsageByAPIKeyChain[] — Per-API-key, per-chain breakdown.
    - `api_key_id` integer, required
    - `name` string, nullable
    - `key_hint` string, required
    - `chain_id` string, required
    - `credits_consumed` number, required
    - `request_count` integer, required
  - `top_methods` UsageTopMethod[] — Top RPC methods by spend.
    - `method` string, required
    - `credits_consumed` number, required
    - `request_count` integer, required
  - `time_series` UsageTimeSeriesPoint[] — Time-bucketed usage data.
    - `bucket` string, date-time, required
    - `credits_consumed` number, required
    - `request_count` integer, required
  - `by_scenario` UsageByScenario[] — Usage by routing outcome scenario.
    - `scenario` string, required — Outcome scenario (e.g. first_hop_success, retry, timeout).
    - `credits_consumed` number, required
    - `request_count` integer, required
  - `groups` object[] — Grouped results when group_by is specified.
    - `api_key_id` integer, nullable
    - `name` string, nullable
    - `key_hint` string, nullable
    - `chain_id` string, nullable
    - `method` string, nullable
    - `scenario` string, nullable
    - `day` string, nullable
    - `credits_consumed` number, required
    - `request_count` integer, required

## Other responses

- `400` — Bad request (invalid time range, include value, group_by, or granularity)
- `401` — Unauthorized
- `500` — Internal server error
- `503` — Usage data temporarily unavailable (ClickHouse)

---

[API](https://skmtc.net/routemesh/apis/routemesh-api.md) · [All operations](https://skmtc.net/routemesh/apis/routemesh-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/routemesh/routemesh-api/versions/6590c9d7229d/schema)