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.

All Account Management endpoints require dashboard authentication via session cookie.

List Accounts

GET /api/accounts · endpoint

Returns all accounts with their status, usage statistics, and reset times.

Response

accounts · array

Array of account objects

Show AccountSummary object

account_id · string · required

Unique account identifier

email · string · required

Account email address

display_name · string · required

Human-readable account name

plan_type · string · required

ChatGPT plan type (e.g., “pro”, “team”)

status · string · required

Account status: active, paused, or deactivated

usage · object

Current usage percentages

Show properties

primary_remaining_percent · number

Primary window remaining capacity (0-100)

secondary_remaining_percent · number

Secondary window remaining capacity (0-100)

reset_at_primary · string

ISO 8601 timestamp when primary window resets

reset_at_secondary · string

ISO 8601 timestamp when secondary window resets

window_minutes_primary · integer

Primary window duration in minutes

window_minutes_secondary · integer

Secondary window duration in minutes

capacity_credits_primary · number

Total primary window capacity

remaining_credits_primary · number

Remaining primary window credits

capacity_credits_secondary · number

Total secondary window capacity

remaining_credits_secondary · number

Remaining secondary window credits

last_refresh_at · string

Last token refresh timestamp

deactivation_reason · string

Reason for deactivation if status is deactivated

auth · object

Authentication token states

Show properties

access · object

expires_at · string

Access token expiry

state · string

Token state

refresh · object

expires_at · string

Refresh token expiry

state · string

Token state

id_token · object

expires_at · string

ID token expiry

state · string

Token state

Example Request

curl -X GET "https://your-instance.com/api/accounts" \
  -H "Cookie: dashboard_session=your-session-token"

Example Response

{
  "accounts": [
    {
      "account_id": "acc_123abc",
      "email": "[e-mail]",
      "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

POST /api/accounts/import · endpoint

Import a ChatGPT account using an auth.json file from the official OpenAI CLI.

Request

auth_json · file · required

The auth.json file containing ChatGPT session tokens. Must be uploaded as multipart/form-data.

Response

account_id · string · required

The imported account ID

email · string · required

Account email address

plan_type · string · required

ChatGPT plan type

status · string · required

Initial account status (typically “active”)

Example Request

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

{
  "account_id": "acc_456def",
  "email": "[e-mail]",
  "plan_type": "pro",
  "status": "active"
}

Error Responses

400 · error

invalid_auth_json: The auth.json file is malformed or missing required fields

409 · error

duplicate_identity_conflict: An account with this identity already exists

Get Account Trends

GET /api/accounts/{account_id}/trends · endpoint

Retrieve historical usage trends for a specific account.

Path Parameters

account_id · string · required

The account ID to fetch trends for

Response

account_id · string · required

The account ID

primary · array · required

Array of usage trend points for primary window

Show UsageTrendPoint

t · string

Timestamp (ISO 8601)

v · number

Usage value

secondary · array · required

Array of usage trend points for secondary window

Example Request

curl -X GET "https://your-instance.com/api/accounts/acc_123abc/trends" \
  -H "Cookie: dashboard_session=your-session-token"

Example Response

{
  "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

404 · error

account_not_found: No account exists with the specified ID

Pause Account

POST /api/accounts/{account_id}/pause · endpoint

Temporarily pause an account, preventing it from being used for requests.

Path Parameters

account_id · string · required

The account ID to pause

Response

status · string · required

Always returns “paused” on success

Example Request

curl -X POST "https://your-instance.com/api/accounts/acc_123abc/pause" \
  -H "Cookie: dashboard_session=your-session-token"

Example Response

{
  "status": "paused"
}

Error Responses

404 · error

account_not_found: No account exists with the specified ID

Reactivate Account

POST /api/accounts/{account_id}/reactivate · endpoint

Reactivate a paused account, making it available for load balancing again.

Path Parameters

account_id · string · required

The account ID to reactivate

Response

status · string · required

Always returns “reactivated” on success

Example Request

curl -X POST "https://your-instance.com/api/accounts/acc_123abc/reactivate" \
  -H "Cookie: dashboard_session=your-session-token"

Example Response

{
  "status": "reactivated"
}

Error Responses

404 · error

account_not_found: No account exists with the specified ID

Delete Account

DELETE /api/accounts/{account_id} · endpoint

Permanently delete an account from the system.

Path Parameters

account_id · string · required

The account ID to delete

Response

status · string · required

Always returns “deleted” on success

Example Request

curl -X DELETE "https://your-instance.com/api/accounts/acc_123abc" \
  -H "Cookie: dashboard_session=your-session-token"

Example Response

{
  "status": "deleted"
}

Error Responses

404 · error

account_not_found: No account exists with the specified ID

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

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