Account Balance

Get balance info	GET https://api.aimlapi.com/v2/billing
Get detailed billing info	GET https://api.aimlapi.com/v2/billing/detail
Get account transactions	GET https://api.aimlapi.com/v2/billing/transactions
Get account balance info (legacy)	GET https://api.aimlapi.com/v1/billing/balance

To make a request, you only need your AIMLAPI key obtained from your account dashboard.

Get balance info

Returns a user's balance.

get

Body

–Optional

Responses

200Success

application/json

current_balancenumberRequired

current user balance in USD.

Example: 123.45

currencystringRequired

balance currency (always USD)

Example: USD

get/v2/billing

curl -L \
  --request GET \
  --url 'https://api.aimlapi.com/v2/billing' \
  --header 'Authorization: Bearer <YOUR_AIMLAPI_KEY>'

200Success

{
  "current_balance": 123.45,
  "currency": "USD"
}

---

Get detailed billing info

Returns detailed billing information, balance and auto top-up settings.

get

Body

–Optional

Responses

200Success

application/json

user_idnumberOptional

User ID.

Example: 111

emailstringOptional

User email.

Example: [e-mail]

current_balancenumberOptional

Current balance in USD.

Example: 100.5

currencystringOptional

Currency (always USD).

Example: USD

get/v2/billing/detail

curl -L \
  --request GET \
  --url 'https://api.aimlapi.com/v2/billing/detail' \
  --header 'Authorization: Bearer <YOUR_AIMLAPI_KEY>'

200Success

{
  "user_id": 111,
  "email": "[e-mail]",
  "current_balance": 100.5,
  "currency": "USD",
  "autotopup_settings": {
    "is_enabled": true,
    "threshold": 50,
    "amount": 100,
    "currency": "USD"
  }
}

---

Get account transactions

The account money feed: one entry per balance movement, either a successful top-up or a charge carrying the model that produced it. Authenticate with a regular AIML API key — there is no key_prefix, because a wallet belongs to the account, not to a key.

For a MODEL_USAGE charge, reference_id is the inference id — the same value returned in the x-inference-id response header and reported as inference_id in Usage Logs.

This is the account ledger — the same figures that move your balance — so it is what you reconcile against. API Key Usage and Usage Logs come from the analytics pipeline instead, and are meant for attribution and budgeting.

A charge lands after you saw your response, and for async video after the generation reports completed, so reconciling the instant a generation finishes will under-count. Failed requests are never charged and have no entry here at all.

Page with the cursor, never with an offset. The ledger grows at the head, so a numeric offset silently skips or repeats entries between pages. Pass pagination.next_cursor back as cursor — it is opaque and accepted only in the exact form we issued, so re-encoding it is rejected with 400.

Returns the account's balance movements, newest first.

get

Query parameters

fromstringOptional

Only return entries created at or after this moment, ISO-8601 with an offset.

Example: 2026-08-01T00:00:00Z

tostringOptional

Only return entries created before this moment, ISO-8601 with an offset. Must be later than from.

Example: 2026-08-18T00:00:00Z

directionstring · enumOptional

Keep only money coming in (TOPUP) or money going out (CHARGE).

Example: CHARGEPossible values:

typestring · enumOptional

Keep only entries of this kind.

Example: MODEL_USAGEPossible values:

limitinteger · min: 1 · max: 100Optional

Entries per page, 1-100.

Default: 50Example: 50

cursorstringOptional

Position to continue from, taken verbatim from the previous response's pagination.next_cursor. The value is opaque and is accepted only in the exact form we issued.

Example: eyJ2IjoxLCJjIjoiMjAyNi0wOC0xN1QxMDowMDowMC4wMDBaIn0

Responses

200

One entry per balance movement, newest first.

application/json

get/v2/billing/transactions

curl -L \
  --request GET \
  --url 'https://api.aimlapi.com/v2/billing/transactions?direction=CHARGE&limit=50' \
  --header 'Authorization: Bearer <YOUR_AIMLAPI_KEY>'

200

One entry per balance movement, newest first.

{
  "data": [
    {
      "created_at": "2026-08-17T10:00:00.000Z",
      "direction": "CHARGE",
      "type": "MODEL_USAGE",
      "amount": {
        "usd": 1.56,
        "credits": 3120000
      },
      "model": "openai/gpt-5",
      "reference_id": "V1StGXR8Z5jdHi6BmyT8k"
    }
  ],
  "pagination": {
    "next_cursor": "eyJ2IjoxLCJjIjoiMjAyNi0wOC0xN1QxMDowMDowMC4wMDBaIn0",
    "has_more": true
  }
}

Errors

Code	When
400	to not later than from; an unknown query parameter; limit outside 1–100; an unknown direction or type; a malformed or re-encoded cursor
401	Missing or invalid key
403	A management key — this route is for regular keys

---

Get account balance info

This endpoint is considered legacy and is scheduled for future deprecation. Please plan to migrate to the /v2/billing and /v2/billing/detail endpoints documented above.

get

Body

–Optional

Responses

200Success

application/json

balancenumberRequired

The total credits associated with the provided API key.

Example: 10000000

lowBalancebooleanRequired

True if the balance is below the threshold.

Example: false

lowBalanceThresholdnumberRequired

Threshold for switching to low balance status.

Example: 10000

lastUpdatedstring · date-timeRequired

The date of the request — i.e., the current date.

Example: 2025-11-25T17:45:00Z

autoDebitStatusstringRequired

Indicates whether auto top-up is enabled for the plan.

Example: disabled

statusstringRequired

The status of the plan associated with the provided API key.

Example: current

statusExplanationstringRequired

A more detailed explanation of the plan status.

Example: Balance is current and up to date

get/v1/billing/balance

curl -L \
  --request GET \
  --url 'https://api.aimlapi.com/v1/billing/balance' \
  --header 'Authorization: Bearer <YOUR_AIMLAPI_KEY>'

200Success

{
  "balance": 10000000,
  "lowBalance": false,
  "lowBalanceThreshold": 10000,
  "lastUpdated": "2025-11-25T17:45:00Z",
  "autoDebitStatus": "disabled",
  "status": "current",
  "statusExplanation": "Balance is current and up to date"
}