---
title: "Get subscription usage"
method: GET
path: "/v1/agents/subscription-usage"
tags: ["Agent credentials"]
---

# Get subscription usage

`GET /v1/agents/subscription-usage`

## Request

- Base URL: `https://api.replicas.dev`
- URL: `https://api.replicas.dev/v1/agents/subscription-usage`
- Auth: HTTP bearer

Reads live from Anthropic and OpenAI how much of each connected Claude and ChatGPT subscription's 5-hour and weekly limits is used. Muse Code and OpenCode Go do not report usage. Without `scope`, returns your personal subscriptions followed by the organization's, each in the order workspaces use them.

## Query parameters

- `scope` 'user' | 'org'

## Headers

- `X-Replicas-Api-Version` '2026-10-07'

## Response `200`

Success

- object
  - `accounts` SubscriptionUsageAccount[], required
    - `provider` 'claude' | 'codex', required
    - `scope` 'user' | 'org', required
    - `credential_id` string, uuid, required
    - `email` string
    - `plan_type` string: Plan name as the provider reports it, e.g. `max` or `pro`
    - `exhausted_until` string, date-time, nullable, required: Workspaces skip the account until then because it last hit a usage limit.
    - `windows` object[], nullable, required: Null when the provider did not report usage. Empty when the plan has no limits.
      - `kind` 'session' | 'weekly', required: `session` is the 5-hour limit.
      - `model` string, nullable, required: Set when the limit covers one model family, e.g. `Opus`.
      - `used_percent` number, required
      - `resets_at` string, date-time, nullable, required: Null until usage starts the window.
    - `reconnect_required` boolean, required: The provider rejected the saved login, so workspaces cannot use the account until it is reconnected.

## Other responses

- `400`: Bad request - Missing or invalid parameters
- `401`: Unauthorized - Invalid or missing API key
- `403`: Forbidden - The authenticated account cannot access this resource

---

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