> ## Documentation Index
> Fetch the complete documentation index at: https://goldrush.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# GoldRush Usage API Now Available

*Published July 26, 2026*

![GoldRush Usage API Now Available](https://www.datocms-assets.com/86369/1785078570-goldrush-usage-api.jpg)

# GoldRush Usage API Now Available

You can now pull your GoldRush account usage programmatically. A new `usage` endpoint returns the same three datasets the Platform **Usage** page renders — daily usage, aggregate credit consumption against your plan, and a per-API-key breakdown — as JSON, filterable by time range.

| Dataset                      | Response field | What it returns                                                                                     |
| ---------------------------- | -------------- | --------------------------------------------------------------------------------------------------- |
| Daily usage                  | `by_day[]`     | Per-day `premium_credits` / `free_credits` over the range                                           |
| Aggregate credit consumption | `aggregate`    | `credits_consumed` vs. `max_credits` (plan ceiling), premium/free split, `plan`, and `flex_credits` |
| Per-API-key breakdown        | `by_api_key[]` | Credits attributed to each `apikey`                                                                 |

Filter with a rolling `duration` (`1`, `3`, `6`, or `12` months; default `1` = month-to-date) or an explicit `from`/`to` window. Every section is computed over that one window (`period`). The endpoint is authenticated with [service keys](https://goldrush.dev/docs/service-keys) (account-scoped), distinct from your standard GoldRush API keys.

**What this unlocks**

* **Budget guardrails in code** — watch `aggregate.credits_consumed` against `max_credits` (and `flex_credits.limit`) to alert or throttle *before* you hit the ceiling.
* **Per-key cost attribution** — use `by_api_key` to split spend across projects, environments, or downstream customers for chargeback and show-back.
* **Usage trends & anomaly detection** — feed `by_day` (premium vs. free) into your own BI/observability stack to forecast month-end spend and catch runaway jobs.
* **Agent self-governance** — let autonomous agents read their own burn rate and premium/free mix, then throttle or switch plans programmatically.

**How to access it**
`GET https://api.covalenthq.com/platform/usage/?duration=1` with a service key (add `from`/`to` for an explicit window), or `goldrush usage --duration 1 --by-key` via the CLI. Response is a `{data:{...}}` envelope.

→ [Read the docs](https://goldrush.dev/docs)