Skip to main content
GET
Get credit usage over a date range

Endpoint

Read your consumption programmatically: how many requests you made over a range of days, how many of them were billable, how many credits they used, broken down per endpoint and per day, together with the balance you have left right now. Use it to reconcile an invoice, to feed your own billing or monitoring, or to forecast when you will need more credits. The same figures are in the dashboard, under Usage report, where they can be downloaded as CSV.

Authentication

Include your API key in the request header:

Parameters

string
First day of the range, YYYY-MM-DD, included. Days are UTC calendar days. Defaults to the first day of the current month.
string
Last day of the range, YYYY-MM-DD, included: the whole UTC day is counted. Defaults to today. A range covers at most 366 days.

Response

string
First UTC day covered, YYYY-MM-DD.
string
Last UTC day covered, YYYY-MM-DD.
number
Your balance now, whatever the range: everything you can still spend, plan allowance plus pay-as-you-go credits. Same figure as on GET /api/v1/subscription.
number
The plan half of creditsRemaining.
number
The pay-as-you-go half of creditsRemaining.
number
Every request made with your API keys over the range, whatever its outcome, refusals (402, 429) and errors included.
number
The requests that cost credits: a delivered response, or a 404 for a record that does not exist. See What is billed.
number
Credits those billable requests used. Higher than billableRequests when you called endpoints that cost more than one credit.
object[]
The same three figures per endpoint, busiest first, with the requests split by HTTP status.
object[]
One entry per UTC day of the range, oldest first, days without traffic at 0. Days that have not started yet are not listed, so a range ending in the future stops at today.

Example Request

Example Response

Errors

See Error Handling for the full list of error codes and recommended handling.
  • 400 INVALID_PARAMETER — a date that is not YYYY-MM-DD, from after to, or more than 366 days
  • 401 UNAUTHENTICATED / INVALID_API_KEY
  • 429 RATE_LIMITED
  • 500 INTERNAL_ERROR
  • 503 SERVICE_UNAVAILABLE

Notes

This endpoint is free: it does not consume credits, and it answers even when you are out of credits. Calls to it and to GET /api/v1/subscription are left out of the figures it reports, so checking your consumption never adds to it.
Like /subscription, it runs on its own budget of 1 request per second per account, separate from your plan’s rate limit and from /subscription’s: it returns X-RateLimit-Cost: 0 and never spends plan throughput. See Rate Limits.
Today’s figures are live: a request shows up within about a minute. To follow a month as it goes, call this endpoint without parameters — it defaults to the current month to date. Consumption is recorded from 16 July 2026; earlier days report 0.

Authorizations

X-API-Key
string
header
required

Query Parameters

from
string<date>

First UTC day of the range, YYYY-MM-DD, included. Defaults to the first day of the current month.

Example:

"2026-10-01"

to
string<date>

Last UTC day of the range, YYYY-MM-DD, included (the whole day is counted). Defaults to today. The range covers at most 366 days.

Example:

"2026-10-31"

Response

Current balance and consumption over the range

from
string<date>
required

First UTC day covered.

Example:

"2026-10-01"

to
string<date>
required

Last UTC day covered.

Example:

"2026-10-03"

creditsRemaining
integer
required

Your balance now, whatever the range: plan allowance plus pay-as-you-go credits. Same figure as on /api/v1/subscription.

Example:

684230

subscriptionCreditsRemaining
integer
required

The plan half of creditsRemaining.

Example:

184230

paygCreditsRemaining
integer
required

The pay-as-you-go half of creditsRemaining.

Example:

500000

requests
integer
required

Every request made with your API keys over the range, whatever its outcome: refusals (402, 429) and errors included. Calls to /subscription and /usage are not counted.

Example:

30482

billableRequests
integer
required

The requests that cost credits: a delivered response, or a 404 for a record that does not exist.

Example:

30214

creditsUsed
integer
required

Credits used by the billable requests. Higher than billableRequests when endpoints costing more than one credit were called.

Example:

32154

endpoints
object[]
required

The same figures per endpoint, busiest first.

days
object[]
required

One entry per UTC day of the range up to today, oldest first, idle days at 0. Days that have not started are not listed.