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

# Get Api Usage

`GET /usage`

Summary + daily / per-key / per-operation aggregates for the caller's team.

Role-scoped: admins/owners see every row in the team; members see only
rows attributable to their own API keys plus their own MCP-origin rows.
Max range 90 days; defaults to the last 7 days when unspecified.

## Query parameters

- `api_key_id` string, nullable — Optional API-key UUID filter. Narrows all aggregates to the given key.
- `from` string, date-time, nullable — ISO8601 UTC lower bound (inclusive). Defaults to ``to - 7d``.
- `to` string, date-time, nullable — ISO8601 UTC upper bound (exclusive). Defaults to ``now``.

## Headers

- `Moda-Version` '2026-04-12' | '2026-05-01'

## Response `200`

Successful Response

- UsageResponse
  - `period` UsagePeriod, required
    - `start` string, date-time, required — Resolved lower bound of the range, ISO8601 UTC.
    - `end` string, date-time, required — Resolved upper bound of the range, ISO8601 UTC.
  - `summary` UsageSummary, required
    - `events_total` integer, required — Total events in the range.
    - `events_succeeded` integer, required — Events with HTTP status 200-399.
    - `events_failed` integer, required — Events with HTTP status >= 400.
    - `credits_used` integer, nullable, required — Sum of ``credits_charged`` across billable events in the range. ``null`` when no event in the window has finalized credits yet (follows the ENG-2516 'never fabricate' billing policy -- we don't want to display ``0`` when the honest answer is 'we don't know yet').
    - `success_rate` number, required — ``events_succeeded / events_total`` rounded to 4 decimals; 0.0 when total is 0.
  - `daily` UsageDaily[], required
    - `date` string, required — UTC calendar date (``YYYY-MM-DD``).
    - `events` integer, required
    - `credits` integer, required
    - `failed` integer, required
  - `by_api_key` UsageByApiKey[], required
    - `api_key_id` string, nullable, required — Raw UUID of the API key; ``null`` when the key was deleted or the row was MCP-origin.
    - `name` string, nullable, required — Human-readable key name; ``null`` when the underlying key row is gone.
    - `events` integer, required
    - `credits` integer, required
    - `last_used_at` string, date-time, required — Most recent event timestamp for this key.
  - `by_operation` UsageByOperation[], required
    - `operation_id` string, required
    - `events` integer, required
    - `credits` integer, required

## Other responses

- `401` — Authentication required.
- `403` — Permission denied for this scope.
- `404` — Resource not found.
- `409` — Conflict (idempotency / resource state).
- `422` — Request validation failed.
- `429` — Rate limit exceeded.
- `500` — Internal error.

---

[API](https://skmtc.dev/moda/apis/moda-public-api.md) · [All operations](https://skmtc.dev/moda/apis/moda-public-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/moda/moda-public-api/revisions/b34cb4cca59e/schema)