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

# Get Usage

`GET /v1/usage`

## Request

- Base URL: `https://api.craterview.ai`
- URL: `https://api.craterview.ai/v1/usage`
- Auth: HTTP bearer

The account's credit balance, and what it has spent, per model.

Account-wide rather than per key, because that is what the balance belongs to.
A job is charged when it succeeds, so work still queued or running is not in these
figures yet, and a job that fails costs nothing. The balance here is the one your next
submission is judged by.

## Response `200`

Successful Response

- UsageResponse
  - `credits` integer, required: Credits spent, all time.
  - `credits_granted` integer, required: Credits added to this account, all time — bought, granted, and arrears written off — less any refunded purchase.
  - `credits_remaining` integer, required: Credits left to spend. Never below zero: work on the community queue is charged and may take an account past its balance, and the arrears are written off the next time credit arrives.
  - `subscribed_until` string, date-time, nullable: When the current subscription's paid period ends, ISO-8601 — null when there is no subscription. Informational: `subscribed` is the answer to which queue your work enters, decided here rather than by comparing this against your own clock.
  - `subscribed` boolean: Whether a subscription is currently putting this account's work on paid compute. While it is true, work runs there at any balance — and the balance means what it always did, because a subscription grants no credit and jobs are charged as usual. A capped subscription gives it for `subscription_allowance` credits of work a period; past that, work runs on the community queue until the period renews.
  - `subscription_allowance` integer, nullable: How many credits of work a period the subscription puts on paid compute, or null for one with no cap and when there is no subscription. Nothing is granted: jobs are charged as usual, and the window holds until the period's charges reach this figure.
  - `subscription_allowance_remaining` integer, nullable: Under a capped subscription, how much of `subscription_allowance` is left this period: how many more credits of work it will put on paid compute. Credit on the account is counted separately, as `credits_remaining`, and is spent first. Null where there is no cap.
  - `is_guest` boolean: Whether this account has no sign-in attached to it. An account created in a browser or on a device starts this way and works normally — it submits, it spends credit, it holds keys. What it cannot do is buy or publish, and it cannot be reached from anywhere else, because there is nothing to sign in with. Signing in attaches one and this becomes false, keeping the same account, keys and history.
  - `jobs` integer, required: Jobs submitted, all time, whatever their outcome.
  - `output_bytes` integer, required: Total size of the results produced, in bytes — the results only, not the input or the preview kept beside them.
  - `by_model` ModelUsage[], required: The same figures broken down per model, largest spend first.
    - `model` string, required: The model the jobs were submitted to.
    - `jobs` integer, required: Jobs submitted to this model, all time, whatever their outcome.
    - `failed` integer, required: Of those, how many failed. A failed job costs nothing.
    - `credits` integer, required: Credits spent on this model, all time.
    - `output_bytes` integer, required: Total size of this model's results, in bytes.
  - `jobs_in_flight` integer: Your jobs queued or running right now.
  - `max_jobs_in_flight` integer, required: The most you may have queued or running at once. Submitting past it is refused with a 429. It is higher once the account is signed in, so read it rather than assuming it.

## Other responses

- `400`: the path, query or a JSON string in the body contains a NUL character or an unpaired surrogate; the body is not JSON encoded as UTF-8, or carries a number JSON cannot represent (NaN, Infinity, or one too large) or nesting too deep to read; or an Idempotency-Key header is longer than 255 characters or not printable ASCII. The request was not read
- `401`: missing, malformed or unrecognised API key
- `413`: the request body is larger than 1 MiB. The request was not read

---

[API](https://skmtc.dev/craterview/apis/craterview-ai-api.md) · [All operations](https://skmtc.dev/craterview/apis/craterview-ai-api/llms.txt) · [OpenAPI document](https://skmtc.dev/craterview/apis/craterview-ai-api/revisions/9419a5cd27cd?raw)