> For the complete documentation index, see [llms.txt](https://docs.aimlapi.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.aimlapi.com/api-references/service-endpoints/account-balance.md). # Account Balance
Get balance infoGET https://api.aimlapi.com/v2/billing
Get detailed billing infoGET https://api.aimlapi.com/v2/billing/detail
Get account transactionsGET 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](https://aimlapi.com/app/keys). ### Get balance info Returns a user's balance. ## GET /v2/billing > ```json {"openapi":"3.0.0","info":{"title":"AIML API","version":"1.0.0"},"servers":[{"url":"https://api.aimlapi.com"}],"paths":{"/v2/billing":{"get":{"operationId":"_v2_billing","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"–","title":"–"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"type":"object","properties":{"current_balance":{"type":"number","description":"current user balance in USD."},"currency":{"type":"string","description":"balance currency (always USD)"}},"required":["current_balance","currency"]}}}}}}}}} ``` *** ### Get detailed billing info Returns detailed billing information, balance and auto top-up settings. ## GET /v2/billing/detail > ```json {"openapi":"3.0.0","info":{"title":"AIML API","version":"1.0.0"},"servers":[{"url":"https://api.aimlapi.com"}],"paths":{"/v2/billing/detail":{"get":{"operationId":"_v2_billing_detail","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"–","title":"–"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"type":"object","properties":{"user_id":{"type":"number","description":"User ID."},"email":{"type":"string","description":"User email."},"current_balance":{"type":"number","description":"Current balance in USD."},"currency":{"type":"string","description":"Currency (always USD)."},"autotopup_settings":{"type":"object","description":"Auto top-up settings.","properties":{"is_enabled":{"type":"boolean","description":"Whether auto top-up is enabled."},"threshold":{"type":"number","description":"Balance threshold that triggers auto top-up (USD)."},"amount":{"type":"number","description":"Auto top-up amount (USD)."},"currency":{"type":"string","description":"Auto top-up currency (always USD)."}},"required":["user_id","email","current_balance","currency","autotopup_settings"]}}}}}}}}}}} ``` *** ### 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](/api-references/service-endpoints/usage-logs.md). {% hint style="info" %} This is the account ledger — the same figures that move your balance — so it is what you reconcile against. [API Key Usage](/api-references/service-endpoints/api-key-usage.md) and [Usage Logs](/api-references/service-endpoints/usage-logs.md) 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. {% endhint %} {% hint style="warning" %} 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`. {% endhint %} Returns the account's balance movements, newest first. ## GET /v2/billing/transactions > ```json {"openapi":"3.0.0","info":{"title":"AIML API","version":"1.0.0"},"servers":[{"url":"https://api.aimlapi.com"}],"paths":{"/v2/billing/transactions":{"get":{"operationId":"_v2_billing_transactions","parameters":[{"name":"from","in":"query","required":false,"description":"Only return entries created at or after this moment, ISO-8601 with an offset.","schema":{"type":"string"}},{"name":"to","in":"query","required":false,"description":"Only return entries created before this moment, ISO-8601 with an offset. Must be later than `from`.","schema":{"type":"string"}},{"name":"direction","in":"query","required":false,"description":"Keep only money coming in (`TOPUP`) or money going out (`CHARGE`).","schema":{"type":"string","enum":["TOPUP","CHARGE"]}},{"name":"type","in":"query","required":false,"description":"Keep only entries of this kind.","schema":{"type":"string","enum":["PAYMENT","BONUS","REFUND","ADJUSTMENT","MODEL_USAGE","CREDITS_EXPIRED","INIT"]}},{"name":"limit","in":"query","required":false,"description":"Entries per page, 1-100.","schema":{"type":"integer","default":50,"minimum":1,"maximum":100}},{"name":"cursor","in":"query","required":false,"description":"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.","schema":{"type":"string"}}],"responses":{"200":{"description":"One entry per balance movement, newest first.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","description":"The requested page of ledger entries.","items":{"type":"object","properties":{"created_at":{"type":"string","description":"When the entry was recorded, in UTC."},"direction":{"type":"string","enum":["TOPUP","CHARGE"],"description":"Which way the money moved. `amount` is always positive, so this is what carries the sign."},"type":{"type":"string","enum":["PAYMENT","BONUS","REFUND","ADJUSTMENT","MODEL_USAGE","CREDITS_EXPIRED","INIT"],"description":"What produced the entry."},"amount":{"type":"object","description":"How much moved, always as a positive number.","properties":{"usd":{"type":"number"},"credits":{"type":"integer"}},"required":["usd","credits"]},"model":{"type":"string","nullable":true,"description":"Model that produced the charge. Null on top-ups, on charges that are not model usage, and when the model could not be resolved."},"reference_id":{"type":"string","nullable":true,"description":"Handle that ties the entry back to something you have. For `MODEL_USAGE` it is the inference id, for a payment it is the payment transaction id. Null when the entry has no caller-side handle, such as a bonus, an expiry or a manual adjustment."}},"required":["created_at","direction","type","amount","model","reference_id"]}},"pagination":{"type":"object","properties":{"next_cursor":{"type":"string","nullable":true,"description":"Pass this back as `cursor` to fetch the next page. Null on the last page."},"has_more":{"type":"boolean","description":"Whether another page follows this one."}},"required":["next_cursor","has_more"]}},"required":["data","pagination"]}}}}}}}}} ``` #### 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 {% hint style="warning" %} 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. {% endhint %} ## GET /v1/billing/balance > ```json {"openapi":"3.0.0","info":{"title":"AIML API","version":"1.0.0"},"servers":[{"url":"https://api.aimlapi.com"}],"paths":{"/v1/billing/balance":{"get":{"operationId":"_v1_billing_balance","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"–","title":"–"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"type":"object","properties":{"balance":{"type":"number","description":"The total credits associated with the provided API key."},"lowBalance":{"type":"boolean","description":"True if the balance is below the threshold."},"lowBalanceThreshold":{"type":"number","description":"Threshold for switching to low balance status."},"lastUpdated":{"type":"string","format":"date-time","description":"The date of the request — i.e., the current date."},"autoDebitStatus":{"type":"string","description":"Indicates whether auto top-up is enabled for the plan."},"status":{"type":"string","description":"The status of the plan associated with the provided API key."},"statusExplanation":{"type":"string","description":"A more detailed explanation of the plan status."}},"required":["balance","lowBalance","lowBalanceThreshold","lastUpdated","autoDebitStatus","status","statusExplanation"]}}}}}}}}} ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.aimlapi.com/api-references/service-endpoints/account-balance.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.