---
title: "Get credit usage over a date range"
method: GET
path: "/api/v1/usage"
---

# Get credit usage over a date range

`GET /api/v1/usage`

## Request

- Base URL: `https://api.fetchin.io`
- URL: `https://api.fetchin.io/api/v1/usage`
- Auth: API key in header `X-API-Key`

Return the authenticated account's current credit balance and its consumption over a range of UTC days: requests, billable requests and credits used, in total, per endpoint (split by HTTP status) and per day. Use it to reconcile an invoice or to feed your own billing and monitoring. Days are UTC calendar days, both ends included; `from` defaults to the first day of the current month and `to` to today, and a range covers at most 366 days. A request is billable when it cost credits: a delivered response, or a 404 for a record that does not exist; refusals (402, 429) and server errors never are. This endpoint is free - it does not consume credits - and answers even when your credits are exhausted. Calls to it and to `/api/v1/subscription` are left out of the figures it reports. Like `/api/v1/subscription`, it is metered on its OWN budget of 1 request per second per account, separate from your plan's per-second limit and from `/subscription`'s: it returns `X-RateLimit-Cost: 0` and carries no `X-RateLimit-Remaining` or `X-RateLimit-Reset`. Today's figures are live, within about a minute. Consumption is recorded from 2026-07-16; earlier days report 0.

## Query parameters

- `from` string, date
- `to` string, date

## Response `200`

Current balance and consumption over the range

- object
  - `from` string, date, required: First UTC day covered.
  - `to` string, date, required: Last UTC day covered.
  - `creditsRemaining` integer, required: Your balance now, whatever the range: plan allowance plus pay-as-you-go credits. Same figure as on /api/v1/subscription.
  - `subscriptionCreditsRemaining` integer, required: The plan half of creditsRemaining.
  - `paygCreditsRemaining` integer, required: The pay-as-you-go half of creditsRemaining.
  - `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.
  - `billableRequests` integer, required: The requests that cost credits: a delivered response, or a 404 for a record that does not exist.
  - `creditsUsed` integer, required: Credits used by the billable requests. Higher than billableRequests when endpoints costing more than one credit were called.
  - `endpoints` object[], required: The same figures per endpoint, busiest first.
    - `endpoint` string, required: The route called.
    - `requests` integer, required
    - `billableRequests` integer, required
    - `creditsUsed` integer, required
    - `statusCodes` object, required: Requests per HTTP status. Sums to requests.
  - `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.
    - `date` string, date, required
    - `requests` integer, required
    - `billableRequests` integer, required
    - `creditsUsed` integer, required

## Other responses

- `400`: Invalid range (INVALID_PARAMETER): a date that is not YYYY-MM-DD, from after to, or more than 366 days.
- `401`: Unauthorized - the X-API-Key header is missing or invalid.
- `429`: Too many requests - you exceeded this endpoint's own budget of 1 request per second per account (RATE_LIMITED). Your plan's per-second budget is untouched by these calls and is not what was exceeded: slow this polling loop, not your data requests. Honor the Retry-After header.
- `500`: Internal server error - an unexpected error occurred in our API. Safe to retry; contact support if it persists.
- `503`: Service unavailable - our API is temporarily unable to serve this request (capacity exhausted or overloaded). This is on our side, not yours and not an upstream service outage. Retry with backoff, honoring the Retry-After header.

---

[API](https://skmtc.dev/fetchin/apis/fetchin-api.md) - [All operations](https://skmtc.dev/fetchin/apis/fetchin-api/llms.txt) - [OpenAPI document](https://skmtc.dev/fetchin/apis/fetchin-api/revisions/19a0b5d0320f?raw)