Skip to main content
GET
Get account usage

Credential

ServiceKey (account-scoped)

Processing

Realtime
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. This endpoint is authenticated with a ServiceKey, an account-scoped credential distinct from your standard GoldRush API keys (cqt_…). See Service Keys for how to create, use, and rotate one.
Platform endpoints on api.covalenthq.com require a trailing slash — call /platform/usage/, not /platform/usage.

Endpoint

Request

Filter with either a rolling duration or an explicit from/to window. Every section of the response is computed over that single window (period).
integer
default:"1"
Rolling window in months, counting back from today. One of 1, 3, 6, or 12. The default 1 is month-to-date. Ignored when from/to are supplied.
string
Start of an explicit window (YYYY-MM-DD). Use together with to instead of duration.
string
End of an explicit window (YYYY-MM-DD). Use together with from instead of duration.

Example

The GoldRush CLI exposes the same data:

Response

The response is a { "data": { … } } envelope containing the window it was computed over (period) and the three datasets.

Field descriptions

object
The single time window every section is computed over.
object
Aggregate credit consumption for the window.
object[]
Per-day usage over the window.
object[]
Credits attributed to each API key over the window.

Common uses

  • 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 — feed by_day (premium vs. free) into your own BI or observability stack to forecast month-end spend and catch runaway jobs.

Common errors