# Get usage

- **Method:** `GET`
- **Path:** `/v1/usage`
- **Operation ID:** `getUsage`
- **Tags:** Account

Returns your plan and the tokens used this period.

## Effective servers

- `https://api.vcp.name`

## Authentication

- **bearer**: HTTP bearer (`API key`)

  An API key from Settings, starting vcp\_live\_.

## Responses

### 200 OK.

**Content type:** `application/json`

schema: `Usage`, no additional properties

- **`period_end` (required)**: `string`, format: `date-time`

  When this token period ends and the next one starts.
- **`period_start` (required)**: `string`, format: `date-time`

  When this token period started.
- **`tier` (required)**: `string`, possible values: `"free", "starter", "premium"`
- **`tokens_limit` (required)**: `integer`, minimum: `0`

  Tokens included in the plan each period.
- **`tokens_used` (required)**: `integer`, minimum: `0`

  Tokens used this period.

**Example:**

```json
{
  "tier": "premium",
  "tokens_used": 188586,
  "tokens_limit": 1500000,
  "period_start": "2026-10-01T00:00:00.000Z",
  "period_end": "2026-11-01T00:00:00.000Z"
}
```

### 401, 403, 429, 500, 503

- `401` The API key is missing, invalid or revoked.
- `403` The account needs a paid plan, or the action is not allowed.
- `429` Too many requests. Retry after the Retry-After header.
- `500` Something went wrong on our side.
- `503` Temporarily unavailable. Retry after the Retry-After header.

**Content type:** `application/json`

schema: `ErrorBody`, no additional properties

- **`error` (required)**: `object`, schema: `ErrorDetail`, no additional properties
  - **`code` (required)**: `string`

    A code from the error tables.
  - **`message` (required)**: `string`

    What went wrong.
  - **`param`**: `string`

    The request field at fault, when there is one.

**Example:**

```json
{
  "error": {
    "code": "invalid_request",
    "message": "text is required.",
    "param": "text"
  }
}
```

## Schemas

### ErrorBody

**Type:** `object`, no additional properties

*Schema `ErrorBody` is shown above.*

**Example:**

```json
{
  "error": {
    "code": "invalid_request",
    "message": "text is required.",
    "param": "text"
  }
}
```

- `ErrorDetail` — shown above.
- `Usage` — shown above.