> ## Documentation Index > Fetch the complete documentation index at: https://routeme.sh/docs/llms.txt > Use this file to discover all available pages before exploring further. # Get usage data > Returns customer-scoped usage aggregates. Supports filtering by time range, chain, API key, grouping, and granularity. By default returns summary and balance. ## OpenAPI ````yaml /api-reference/openapi.json get /usage openapi: 3.0.0 info: title: RouteMesh API version: 1.0.0 description: >- HTTP API for routing JSON-RPC requests across providers, managing API keys, and viewing usage. license: name: Proprietary url: https://routeme.sh servers: - url: https://lb.routeme.sh description: Primary API endpoint - url: https://lb2.routeme.sh description: AWS DNS load balancer (backup) security: [] tags: - name: RPC description: Forward JSON-RPC requests to the router. - name: Chains description: Discover supported chains. - name: API Keys description: Manage your API keys for self-service access. - name: Usage description: View your usage and billing data. - name: Health description: Service health checks. paths: /usage: get: tags: - Usage summary: Get usage data description: >- Returns customer-scoped usage aggregates. Supports filtering by time range, chain, API key, grouping, and granularity. By default returns summary and balance. operationId: getUsage parameters: - name: from in: query description: Start time (RFC3339). Defaults to 30 days ago. schema: type: string format: date-time example: '2025-01-01T00:00:00Z' - name: to in: query description: End time (RFC3339). Defaults to now. schema: type: string format: date-time example: '2025-07-01T00:00:00Z' - name: include in: query description: >- Comma-separated list of sections to include. Options: summary, balance, by_chain, by_api_key, by_api_key_chain, top_methods, time_series, by_scenario. Default: summary,balance. schema: type: string example: summary,balance,by_chain,by_api_key - name: group_by in: query description: >- Group usage by a dimension. Options: chain, api_key, api_key,chain, method, day. schema: type: string example: chain - name: granularity in: query description: 'Time bucket size. Options: day, hour. Default: day.' schema: type: string enum: - day - hour example: day - name: chain_id in: query description: Filter by chain ID (e.g. 1, 137, 8453). schema: type: string example: '1' - name: api_key_id in: query description: Filter by API key numeric ID (found in list response). schema: type: integer example: 1 - name: limit in: query description: Maximum number of rows returned (default and max depend on config). schema: type: integer minimum: 1 example: 100 responses: '200': description: Usage data content: application/json: schema: $ref: '#/components/schemas/UsageResponse' '400': description: >- Bad request (invalid time range, include value, group_by, or granularity) '401': description: Unauthorized '500': description: Internal server error '503': description: Usage data temporarily unavailable (ClickHouse) security: - MgmtKeyAuth: [] components: schemas: UsageResponse: type: object properties: customer_id: type: integer period: $ref: '#/components/schemas/UsagePeriod' summary: $ref: '#/components/schemas/UsageSummary' description: Aggregate credits and request count. balance: $ref: '#/components/schemas/UsageBalance' description: Current credit balance. by_chain: type: array items: $ref: '#/components/schemas/UsageByChain' description: Per-chain breakdown. by_api_key: type: array items: $ref: '#/components/schemas/UsageByAPIKey' description: Per-API-key breakdown. by_api_key_chain: type: array items: $ref: '#/components/schemas/UsageByAPIKeyChain' description: Per-API-key, per-chain breakdown. top_methods: type: array items: $ref: '#/components/schemas/UsageTopMethod' description: Top RPC methods by spend. time_series: type: array items: $ref: '#/components/schemas/UsageTimeSeriesPoint' description: Time-bucketed usage data. by_scenario: type: array items: $ref: '#/components/schemas/UsageByScenario' description: Usage by routing outcome scenario. groups: type: array items: type: object properties: api_key_id: type: integer nullable: true name: type: string nullable: true key_hint: type: string nullable: true chain_id: type: string nullable: true method: type: string nullable: true scenario: type: string nullable: true day: type: string nullable: true credits_consumed: type: number request_count: type: integer format: int64 required: - credits_consumed - request_count description: Grouped results when group_by is specified. required: - customer_id - period additionalProperties: false UsagePeriod: type: object properties: from: type: string format: date-time to: type: string format: date-time required: - from - to UsageSummary: type: object properties: credits_consumed: type: number description: Total credits spent in the period. request_count: type: integer format: int64 description: Total number of requests. credits_per_request: type: number description: Average cost per request. required: - credits_consumed - request_count - credits_per_request UsageBalance: type: object properties: credits: type: number description: Current credit balance. as_of: type: string format: date-time description: Timestamp of the balance snapshot. required: - credits - as_of UsageByChain: type: object properties: chain_id: type: string credits_consumed: type: number request_count: type: integer format: int64 required: - chain_id - credits_consumed - request_count UsageByAPIKey: type: object properties: api_key_id: type: integer name: type: string nullable: true key_hint: type: string description: Masked API key (e.g. rm_a…456). credits_consumed: type: number request_count: type: integer format: int64 required: - api_key_id - key_hint - credits_consumed - request_count UsageByAPIKeyChain: type: object properties: api_key_id: type: integer name: type: string nullable: true key_hint: type: string chain_id: type: string credits_consumed: type: number request_count: type: integer format: int64 required: - api_key_id - key_hint - chain_id - credits_consumed - request_count UsageTopMethod: type: object properties: method: type: string credits_consumed: type: number request_count: type: integer format: int64 required: - method - credits_consumed - request_count UsageTimeSeriesPoint: type: object properties: bucket: type: string format: date-time credits_consumed: type: number request_count: type: integer format: int64 required: - bucket - credits_consumed - request_count UsageByScenario: type: object properties: scenario: type: string description: Outcome scenario (e.g. first_hop_success, retry, timeout). credits_consumed: type: number request_count: type: integer format: int64 required: - scenario - credits_consumed - request_count securitySchemes: MgmtKeyAuth: type: apiKey in: header name: X-Mgmt-Key description: >- Management API key from the RouteMesh dashboard. Required for customer API endpoints (/api-keys, /usage). Each request also carries the customer's RPC API key in the URL path for the RPC endpoint. ````