# Usage API reference

> HTML version: https://storeshot.art/docs/api/usage/

Credit balance and generation usage. Contract 1.18.0; base URL `https://api.storeshot.art/v1`. Schemas: https://storeshot.art/docs/api/schemas.md

## GET /credits

**Credit balance** (operation `getCredits`). Auth: API key with scope `usage:read`, or access token.

Requires `usage:read`. Remaining credits of the account, per balance. Reading never creates or grants credits.

**When to use.** Before spending with a live key, to tell your human the balance (a screenshot-set quote shows it too).

**Credits.** Free: no credits.

**Responses:**

| Status | Description | Schema | Headers |
|---|---|---|---|
| `200` | The balances. | `CreditBalances` | `X-Request-Id`, `RateLimit`, `RateLimit-Policy` |
| `400` | `INVALID_INPUT`. A credential sent in the query string is refused before authentication, without RateLimit headers. | `ErrorEnvelope` | `X-Request-Id`, `RateLimit`, `RateLimit-Policy` |
| `401` | `UNAUTHORIZED`: missing, malformed, unknown, revoked or expired credential. | `ErrorEnvelope` | `X-Request-Id` |
| `403` | `FORBIDDEN`: see `details.reason`. | `ErrorEnvelope` | `X-Request-Id`, `RateLimit`, `RateLimit-Policy` |
| `429` | `RATE_LIMITED`: the request rate of the API key (`details.scope` `key`) or of the account (`user`) is exhausted for this window, or too many failed authentication attempts came from this IP (no `details.scope` and no RateLimit headers). Retry after `Retry-After` seconds. | `ErrorEnvelope` | `X-Request-Id`, `RateLimit`, `RateLimit-Policy`, `Retry-After` |
| `default` | Error (see ErrorEnvelope and /v1/docs/errors). | `ErrorEnvelope` | `X-Request-Id`, `RateLimit`, `RateLimit-Policy` |

Example 200 response:

```json
{
  "balances": {
    "starter": 0,
    "subscription": 0,
    "purchased": 4
  },
  "total": 4
}
```

## GET /usage

**Generation usage** (operation `getUsage`). Auth: API key with scope `usage:read`, or access token.

Requires `usage:read`. Live generations and the credits they used, for the whole account (every API key and surface) in `[from, to)`, bucketed by UTC day, API key or source. Test-key generations are free and not counted. A range may span at most 366 days.

**Credits.** Free: no credits.

**Parameters:**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `from` | query | `string` | no | Start, inclusive. `YYYY-MM-DD` means 00:00 UTC that day. Default: 00:00 UTC 29 days before the day of `to`. |
| `to` | query | `string` | no | End, exclusive. `YYYY-MM-DD` includes that whole UTC day. Default: now. At most 366 days after `from`. |
| `groupBy` | query | `UsageGroupBy` | no | Default: "day" |

**Responses:**

| Status | Description | Schema | Headers |
|---|---|---|---|
| `200` | The usage report. | `UsageReport` | `X-Request-Id`, `RateLimit`, `RateLimit-Policy` |
| `400` | `INVALID_INPUT`. A credential sent in the query string is refused before authentication, without RateLimit headers. | `ErrorEnvelope` | `X-Request-Id`, `RateLimit`, `RateLimit-Policy` |
| `401` | `UNAUTHORIZED`: missing, malformed, unknown, revoked or expired credential. | `ErrorEnvelope` | `X-Request-Id` |
| `403` | `FORBIDDEN`: see `details.reason`. | `ErrorEnvelope` | `X-Request-Id`, `RateLimit`, `RateLimit-Policy` |
| `429` | `RATE_LIMITED`: the request rate of the API key (`details.scope` `key`) or of the account (`user`) is exhausted for this window, or too many failed authentication attempts came from this IP (no `details.scope` and no RateLimit headers). Retry after `Retry-After` seconds. | `ErrorEnvelope` | `X-Request-Id`, `RateLimit`, `RateLimit-Policy`, `Retry-After` |
| `default` | Error (see ErrorEnvelope and /v1/docs/errors). | `ErrorEnvelope` | `X-Request-Id`, `RateLimit`, `RateLimit-Policy` |

Example 200 response:

```json
{
  "from": "2026-10-20T00:00:00.000Z",
  "to": "2026-10-21T14:03:12.000Z",
  "groupBy": "day",
  "data": [
    {
      "key": "2026-10-20",
      "generations": 0,
      "succeeded": 0,
      "failed": 0,
      "refunded": 0,
      "pending": 0,
      "creditsUsed": 0
    },
    {
      "key": "2026-10-21",
      "generations": 3,
      "succeeded": 2,
      "failed": 0,
      "refunded": 1,
      "pending": 0,
      "creditsUsed": 2
    }
  ],
  "totals": {
    "generations": 3,
    "succeeded": 2,
    "failed": 0,
    "refunded": 1,
    "pending": 0,
    "creditsUsed": 2
  }
}
```