> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/Soju06/codex-lb/llms.txt
> Use this file to discover all available pages before exploring further.

# Account Management

> Manage ChatGPT accounts for load balancing and pooling

## Overview

The Account Management API allows you to manage ChatGPT accounts used by Codex-LB for load balancing. You can import accounts, list them with usage statistics, pause/reactivate accounts, and view usage trends.

<Note>
  All Account Management endpoints require dashboard authentication via session cookie.
</Note>

## List Accounts

<ParamField path="GET /api/accounts" type="endpoint">
  Returns all accounts with their status, usage statistics, and reset times.
</ParamField>

### Response

<ResponseField name="accounts" type="array">
  Array of account objects

  <Expandable title="AccountSummary object">
    <ResponseField name="account_id" type="string" required>
      Unique account identifier
    </ResponseField>

    <ResponseField name="email" type="string" required>
      Account email address
    </ResponseField>

    <ResponseField name="display_name" type="string" required>
      Human-readable account name
    </ResponseField>

    <ResponseField name="plan_type" type="string" required>
      ChatGPT plan type (e.g., "pro", "team")
    </ResponseField>

    <ResponseField name="status" type="string" required>
      Account status: `active`, `paused`, or `deactivated`
    </ResponseField>

    <ResponseField name="usage" type="object">
      Current usage percentages

      <Expandable title="properties">
        <ResponseField name="primary_remaining_percent" type="number">
          Primary window remaining capacity (0-100)
        </ResponseField>

        <ResponseField name="secondary_remaining_percent" type="number">
          Secondary window remaining capacity (0-100)
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="reset_at_primary" type="string">
      ISO 8601 timestamp when primary window resets
    </ResponseField>

    <ResponseField name="reset_at_secondary" type="string">
      ISO 8601 timestamp when secondary window resets
    </ResponseField>

    <ResponseField name="window_minutes_primary" type="integer">
      Primary window duration in minutes
    </ResponseField>

    <ResponseField name="window_minutes_secondary" type="integer">
      Secondary window duration in minutes
    </ResponseField>

    <ResponseField name="capacity_credits_primary" type="number">
      Total primary window capacity
    </ResponseField>

    <ResponseField name="remaining_credits_primary" type="number">
      Remaining primary window credits
    </ResponseField>

    <ResponseField name="capacity_credits_secondary" type="number">
      Total secondary window capacity
    </ResponseField>

    <ResponseField name="remaining_credits_secondary" type="number">
      Remaining secondary window credits
    </ResponseField>

    <ResponseField name="last_refresh_at" type="string">
      Last token refresh timestamp
    </ResponseField>

    <ResponseField name="deactivation_reason" type="string">
      Reason for deactivation if status is `deactivated`
    </ResponseField>

    <ResponseField name="auth" type="object">
      Authentication token states

      <Expandable title="properties">
        <ResponseField name="access" type="object">
          <ResponseField name="expires_at" type="string">Access token expiry</ResponseField>
          <ResponseField name="state" type="string">Token state</ResponseField>
        </ResponseField>

        <ResponseField name="refresh" type="object">
          <ResponseField name="expires_at" type="string">Refresh token expiry</ResponseField>
          <ResponseField name="state" type="string">Token state</ResponseField>
        </ResponseField>

        <ResponseField name="id_token" type="object">
          <ResponseField name="expires_at" type="string">ID token expiry</ResponseField>
          <ResponseField name="state" type="string">Token state</ResponseField>
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

### Example Request

```bash theme={null}
curl -X GET "https://your-instance.com/api/accounts" \
  -H "Cookie: dashboard_session=your-session-token"
```

### Example Response

```json theme={null}
{
  "accounts": [
    {
      "account_id": "acc_123abc",
      "email": "user@example.com",
      "display_name": "Production Account",
      "plan_type": "pro",
      "status": "active",
      "usage": {
        "primary_remaining_percent": 75.5,
        "secondary_remaining_percent": 90.2
      },
      "reset_at_primary": "2026-03-04T00:00:00Z",
      "reset_at_secondary": "2026-03-10T00:00:00Z",
      "window_minutes_primary": 1440,
      "window_minutes_secondary": 10080,
      "capacity_credits_primary": 1000.0,
      "remaining_credits_primary": 755.0,
      "capacity_credits_secondary": 5000.0,
      "remaining_credits_secondary": 4510.0,
      "last_refresh_at": "2026-03-03T18:30:00Z",
      "deactivation_reason": null
    }
  ]
}
```

## Import Account

<ParamField path="POST /api/accounts/import" type="endpoint">
  Import a ChatGPT account using an auth.json file from the official OpenAI CLI.
</ParamField>

### Request

<ParamField body="auth_json" type="file" required>
  The auth.json file containing ChatGPT session tokens. Must be uploaded as `multipart/form-data`.
</ParamField>

### Response

<ResponseField name="account_id" type="string" required>
  The imported account ID
</ResponseField>

<ResponseField name="email" type="string" required>
  Account email address
</ResponseField>

<ResponseField name="plan_type" type="string" required>
  ChatGPT plan type
</ResponseField>

<ResponseField name="status" type="string" required>
  Initial account status (typically "active")
</ResponseField>

### Example Request

```bash theme={null}
curl -X POST "https://your-instance.com/api/accounts/import" \
  -H "Cookie: dashboard_session=your-session-token" \
  -F "auth_json=@/path/to/auth.json"
```

### Example Response

```json theme={null}
{
  "account_id": "acc_456def",
  "email": "newuser@example.com",
  "plan_type": "pro",
  "status": "active"
}
```

### Error Responses

<ResponseField name="400" type="error">
  **invalid\_auth\_json**: The auth.json file is malformed or missing required fields
</ResponseField>

<ResponseField name="409" type="error">
  **duplicate\_identity\_conflict**: An account with this identity already exists
</ResponseField>

## Get Account Trends

<ParamField path="GET /api/accounts/{account_id}/trends" type="endpoint">
  Retrieve historical usage trends for a specific account.
</ParamField>

### Path Parameters

<ParamField path="account_id" type="string" required>
  The account ID to fetch trends for
</ParamField>

### Response

<ResponseField name="account_id" type="string" required>
  The account ID
</ResponseField>

<ResponseField name="primary" type="array" required>
  Array of usage trend points for primary window

  <Expandable title="UsageTrendPoint">
    <ResponseField name="t" type="string">Timestamp (ISO 8601)</ResponseField>
    <ResponseField name="v" type="number">Usage value</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="secondary" type="array" required>
  Array of usage trend points for secondary window
</ResponseField>

### Example Request

```bash theme={null}
curl -X GET "https://your-instance.com/api/accounts/acc_123abc/trends" \
  -H "Cookie: dashboard_session=your-session-token"
```

### Example Response

```json theme={null}
{
  "account_id": "acc_123abc",
  "primary": [
    { "t": "2026-03-03T00:00:00Z", "v": 850.5 },
    { "t": "2026-03-03T01:00:00Z", "v": 820.3 },
    { "t": "2026-03-03T02:00:00Z", "v": 755.0 }
  ],
  "secondary": [
    { "t": "2026-03-03T00:00:00Z", "v": 4800.0 },
    { "t": "2026-03-03T01:00:00Z", "v": 4650.0 },
    { "t": "2026-03-03T02:00:00Z", "v": 4510.0 }
  ]
}
```

### Error Responses

<ResponseField name="404" type="error">
  **account\_not\_found**: No account exists with the specified ID
</ResponseField>

## Pause Account

<ParamField path="POST /api/accounts/{account_id}/pause" type="endpoint">
  Temporarily pause an account, preventing it from being used for requests.
</ParamField>

### Path Parameters

<ParamField path="account_id" type="string" required>
  The account ID to pause
</ParamField>

### Response

<ResponseField name="status" type="string" required>
  Always returns "paused" on success
</ResponseField>

### Example Request

```bash theme={null}
curl -X POST "https://your-instance.com/api/accounts/acc_123abc/pause" \
  -H "Cookie: dashboard_session=your-session-token"
```

### Example Response

```json theme={null}
{
  "status": "paused"
}
```

### Error Responses

<ResponseField name="404" type="error">
  **account\_not\_found**: No account exists with the specified ID
</ResponseField>

## Reactivate Account

<ParamField path="POST /api/accounts/{account_id}/reactivate" type="endpoint">
  Reactivate a paused account, making it available for load balancing again.
</ParamField>

### Path Parameters

<ParamField path="account_id" type="string" required>
  The account ID to reactivate
</ParamField>

### Response

<ResponseField name="status" type="string" required>
  Always returns "reactivated" on success
</ResponseField>

### Example Request

```bash theme={null}
curl -X POST "https://your-instance.com/api/accounts/acc_123abc/reactivate" \
  -H "Cookie: dashboard_session=your-session-token"
```

### Example Response

```json theme={null}
{
  "status": "reactivated"
}
```

### Error Responses

<ResponseField name="404" type="error">
  **account\_not\_found**: No account exists with the specified ID
</ResponseField>

## Delete Account

<ParamField path="DELETE /api/accounts/{account_id}" type="endpoint">
  Permanently delete an account from the system.
</ParamField>

### Path Parameters

<ParamField path="account_id" type="string" required>
  The account ID to delete
</ParamField>

### Response

<ResponseField name="status" type="string" required>
  Always returns "deleted" on success
</ResponseField>

### Example Request

```bash theme={null}
curl -X DELETE "https://your-instance.com/api/accounts/acc_123abc" \
  -H "Cookie: dashboard_session=your-session-token"
```

### Example Response

```json theme={null}
{
  "status": "deleted"
}
```

### Error Responses

<ResponseField name="404" type="error">
  **account\_not\_found**: No account exists with the specified ID
</ResponseField>

<Warning>
  Account deletion is permanent and cannot be undone. The account will immediately stop being used for load balancing.
</Warning>

## Authentication

All account management endpoints require dashboard authentication. You must be logged in to the dashboard and include your session cookie in requests.

## Common Error Codes

| Code                          | Description                                  |
| ----------------------------- | -------------------------------------------- |
| `account_not_found`           | The specified account ID does not exist      |
| `invalid_auth_json`           | The auth.json file is invalid or malformed   |
| `duplicate_identity_conflict` | An account with this identity already exists |