> ## Documentation Index > Fetch the complete documentation index at: https://docs.amlok.io/llms.txt > Use this file to discover all available pages before exploring further. # Retrieve credit balance > Read available_credits, the single spendable balance, and spent_credits, cumulative product charges less correcting reversals since account opening. There are no reserved, held or separate posted-credit balances. Successful paid and promotional top-ups add to available credits with no consumption priority; payments still in progress are not credits. Actual product charges reduce available credits and increase spent credits atomically. Final refunds reduce available credits without increasing spent credits. The automatic top-up trigger compares available_credits with the configured threshold, at least CAD 200. Processing can continue below the trigger while funded. Cancellation immediately stops deductions; all remaining available credits are refunded at month-end closure. This endpoint is read-only. Required scope: billing:read. The API key is bound to exactly one workspace, institution and environment. There is no workspace override; this binding applies to every read and export. **Required scope:** `billing:read` Read available\_credits, the single spendable balance, and spent\_credits, cumulative product charges less correcting reversals since account opening. There are no reserved, held or separate posted-credit balances. Successful paid and promotional top-ups add to available credits with no consumption priority; payments still in progress are not credits. Actual product charges reduce available credits and increase spent credits atomically. Final refunds reduce available credits without increasing spent credits. The automatic top-up trigger compares available\_credits with the configured threshold, at least CAD 200. Processing can continue below the trigger while funded. Cancellation immediately stops deductions; all remaining available credits are refunded at month-end closure. This endpoint is read-only. Required scope: billing:read. The API key is bound to exactly one workspace, institution and environment. There is no workspace override; this binding applies to every read and export. [Product scope](https://docs.amlok.io/api-reference/products-and-endpoints.md) · [Processing lifecycle](https://docs.amlok.io/api-reference/processing-lifecycle.md) · [Errors](https://docs.amlok.io/api-reference/errors.md) ## OpenAPI ````yaml openapi/amlok-v1.json GET /v1/billing/credits openapi: 3.1.0 info: title: AMLOK API version: 1.4.2 description: >- API reference for AMLOK 1.4.2, with example requests and responses. Configure your institution-issued environment URL before making requests. x-source-workbook: >- https://docs.google.com/spreadsheets/d/14pU2PLv9JDda8gAa1367hipa2oJQB260fIJthevrp10/edit servers: - url: https://api.example.com description: Set the server URL to your institution-issued AMLOK environment URL. security: - BearerAuth: [] tags: - name: Platform description: Platform operations. - name: Identity description: Identity operations. - name: Banking description: Banking operations. - name: Payments description: Payments operations. - name: Commerce description: Commerce operations. - name: Accounting description: Accounting operations. - name: Inventory description: Inventory operations. - name: Lending description: Lending operations. - name: Liens description: Liens operations. - name: Risk description: Risk operations. - name: Operations description: Operations operations. - name: Webhooks description: Webhooks operations. - name: Reporting description: Reporting operations. paths: /v1/billing/credits: get: tags: - Reporting summary: Retrieve credit balance description: >- Read available_credits, the single spendable balance, and spent_credits, cumulative product charges less correcting reversals since account opening. There are no reserved, held or separate posted-credit balances. Successful paid and promotional top-ups add to available credits with no consumption priority; payments still in progress are not credits. Actual product charges reduce available credits and increase spent credits atomically. Final refunds reduce available credits without increasing spent credits. The automatic top-up trigger compares available_credits with the configured threshold, at least CAD 200. Processing can continue below the trigger while funded. Cancellation immediately stops deductions; all remaining available credits are refunded at month-end closure. This endpoint is read-only. Required scope: billing:read. The API key is bound to exactly one workspace, institution and environment. There is no workspace override; this binding applies to every read and export. operationId: WA058 parameters: - name: snapshot_id in: query required: false description: >- Reuse an immutable snapshot from this workspace. Omit to use a current snapshot. Cursors bind this value; unknown snapshots return 404 and conflicting cursor parameters return 400. schema: type: string example: billing_snapshot_example responses: '200': description: Successful response. headers: X-Request-ID: schema: type: string ETag: schema: type: string example: '"1:billing_snapshot_example"' X-Billing-Snapshot-ID: description: >- Snapshot for this entire response and all pages. Reuse for cross-report reconciliation. schema: type: string minLength: 1 example: billing_snapshot_example content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/BillingCreditBalance' meta: $ref: '#/components/schemas/ResponseMeta' required: - data - meta examples: synthetic: summary: Synthetic retrieve credit balance value: data: id: billing_credit_balance_example object: billing_credit_balance record_version: 1 created_at: '2026-10-23T14:00:00Z' updated_at: '2026-10-23T14:00:00Z' workspace_id: wsp_example billing_account_id: billing_account_example currency: CAD as_of: '2026-10-23T14:00:00Z' ledger_sequence: 3 available_credits: '11992.00' spent_credits: '8.00' snapshot_id: billing_snapshot_example meta: request_id: req_example schema_version: 1.4.2 generated_at: '2026-10-23T14:00:00Z' data_status: complete '400': $ref: '#/components/responses/Error400' '401': $ref: '#/components/responses/Error401' '403': $ref: '#/components/responses/Error403' '404': $ref: '#/components/responses/Error404' '409': $ref: '#/components/responses/Error409' '412': $ref: '#/components/responses/Error412' '422': $ref: '#/components/responses/Error422' '429': $ref: '#/components/responses/Error429' '500': $ref: '#/components/responses/Error500' '503': $ref: '#/components/responses/Error503' security: - BearerAuth: [] x-codeSamples: - lang: Shell label: cURL source: |- curl --request GET --fail-with-body --max-time 30 \ "${AMLOK_API_BASE_URL}/v1/billing/credits?snapshot_id=billing_snapshot_example" \ --header "Authorization: Bearer ${AMLOK_API_KEY}" \ --header "Accept: application/json" - lang: Python source: |- import os import requests base_url = os.environ["AMLOK_API_BASE_URL"].rstrip("/") headers = {'Accept': 'application/json'} headers["Authorization"] = "Bearer " + os.environ["AMLOK_API_KEY"] response = requests.request( "GET", base_url + "/v1/billing/credits?snapshot_id=billing_snapshot_example", headers=headers, timeout=30, allow_redirects=False, ) response.raise_for_status() print(response.json()) - lang: JavaScript label: Node.js source: >- const baseUrl = process.env.AMLOK_API_BASE_URL; const apiKey = process.env.AMLOK_API_KEY; if (!baseUrl || !apiKey) throw new Error("Configure AMLOK_API_BASE_URL and AMLOK_API_KEY"); const headers = { "Accept": "application/json" }; headers.Authorization = `Bearer ${apiKey}`; const response = await fetch(baseUrl.replace(/\/$/, "") + "/v1/billing/credits?snapshot_id=billing_snapshot_example", { method: "GET", headers, redirect: "error", signal: AbortSignal.timeout(30000), }); if (!response.ok) throw new Error(`AMLOK returned HTTP ${response.status}`); console.log(await response.json()); components: schemas: BillingCreditBalance: type: object properties: id: type: string minLength: 1 object: type: string minLength: 1 record_version: type: integer minimum: 1 created_at: type: string format: date-time updated_at: type: string format: date-time workspace_id: type: string minLength: 1 description: Authorized workspace whose unified billing account owns this report. billing_account_id: type: string minLength: 1 currency: type: string enum: - CAD as_of: type: string format: date-time ledger_sequence: type: integer minimum: 0 available_credits: type: string pattern: ^(0|[1-9][0-9]*)\.[0-9]{2}$ description: >- One spendable CAD balance. Top-ups increase it; completed product charges and final refunds decrease it. There are no reserved credits or separate posted-credit balances. spent_credits: type: string pattern: ^(0|[1-9][0-9]*)\.[0-9]{2}$ description: >- Cumulative product charges minus correcting reversals since account opening, at this snapshot. Refunds are not product spend. Read consumption reports for a particular period. snapshot_id: type: string minLength: 1 description: >- Immutable workspace billing snapshot used for this financial representation. required: - id - object - record_version - created_at - updated_at - workspace_id - billing_account_id - currency - as_of - ledger_sequence - available_credits - spent_credits - snapshot_id additionalProperties: false ResponseMeta: type: object properties: request_id: type: string description: AMLOK request correlation ID. schema_version: type: string description: Serialization contract version. generated_at: type: string format: date-time description: Response generation time, not source data freshness. data_status: $ref: '#/components/schemas/Enum_data_status' description: Completeness of this response within its declared scope. coverage: anyOf: - $ref: '#/components/schemas/Coverage' - type: 'null' description: Requested and achieved source/time coverage. required: - request_id - schema_version - generated_at - data_status Enum_data_status: type: string enum: - complete - partial - unavailable - pending Coverage: type: object properties: requested_from: anyOf: - type: string format: date - type: 'null' description: Inclusive start requested. requested_to: anyOf: - type: string format: date - type: 'null' description: Exclusive end requested. available_from: anyOf: - type: string format: date - type: 'null' description: Earliest actual coverage. available_to: anyOf: - type: string format: date - type: 'null' description: Exclusive end of actual coverage. source_ids: type: array items: type: string description: Sources actually contributing. missing_intervals: type: array items: $ref: '#/components/schemas/Interval' description: Known gaps within requested scope. jurisdictions_completed: anyOf: - type: array items: type: string - type: 'null' description: Completed geographic search scope when applicable. required: - source_ids - missing_intervals ErrorEnvelope: type: object properties: error: $ref: '#/components/schemas/Error' meta: $ref: '#/components/schemas/ResponseMeta' required: - error - meta Interval: type: object properties: from: type: string format: date description: Inclusive interval start. to: type: string format: date description: Exclusive interval end. required: - from - to Error: type: object properties: code: type: string description: Stable machine-readable error code. message: type: string description: Safe caller-facing explanation. field: anyOf: - type: string - type: 'null' description: Invalid request field when relevant. retryable: type: boolean description: Whether retry may succeed without changing the request. request_id: type: string description: Correlation identifier for support. required: - code - message - retryable - request_id responses: Error400: description: Request failed. Inspect error.code and error.retryable. headers: X-Request-ID: description: AMLOK response correlation identifier. schema: type: string example: req_example content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' examples: invalid_request: summary: invalid_request value: error: code: invalid_request message: Malformed input, unknown parameter or incompatible filters. retryable: false request_id: req_example meta: request_id: req_example schema_version: 1.4.2 generated_at: '2026-10-23T14:00:00Z' data_status: complete unsupported_parameter: summary: unsupported_parameter value: error: code: unsupported_parameter message: Historical query or filter not implemented on this resource. retryable: false request_id: req_example meta: request_id: req_example schema_version: 1.4.2 generated_at: '2026-10-23T14:00:00Z' data_status: complete validation_error: summary: validation_error value: error: code: validation_error message: >- A field, projection, or request value is invalid. Inspect error.field. retryable: false request_id: req_example meta: request_id: req_example schema_version: 1.4.2 generated_at: '2026-10-23T14:00:00Z' data_status: complete Error401: description: Request failed. Inspect error.code and error.retryable. headers: X-Request-ID: description: AMLOK response correlation identifier. schema: type: string example: req_example content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' examples: unauthenticated: summary: unauthenticated value: error: code: unauthenticated message: Missing, expired or invalid credential. retryable: false request_id: req_example meta: request_id: req_example schema_version: 1.4.2 generated_at: '2026-10-23T14:00:00Z' data_status: complete Error403: description: Request failed. Inspect error.code and error.retryable. headers: X-Request-ID: description: AMLOK response correlation identifier. schema: type: string example: req_example content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' examples: forbidden: summary: forbidden value: error: code: forbidden message: Tenant scope or field/product entitlement missing. retryable: false request_id: req_example meta: request_id: req_example schema_version: 1.4.2 generated_at: '2026-10-23T14:00:00Z' data_status: complete Error404: description: Request failed. Inspect error.code and error.retryable. headers: X-Request-ID: description: AMLOK response correlation identifier. schema: type: string example: req_example content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' examples: not_found: summary: not_found value: error: code: not_found message: Record does not exist or is not visible in this tenant. retryable: false request_id: req_example meta: request_id: req_example schema_version: 1.4.2 generated_at: '2026-10-23T14:00:00Z' data_status: complete Error409: description: Request failed. Inspect error.code and error.retryable. headers: X-Request-ID: description: AMLOK response correlation identifier. schema: type: string example: req_example content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' examples: idempotency_conflict: summary: idempotency_conflict value: error: code: idempotency_conflict message: Same key was reused with different intended input. retryable: false request_id: req_example meta: request_id: req_example schema_version: 1.4.2 generated_at: '2026-10-23T14:00:00Z' data_status: complete invalid_state: summary: invalid_state value: error: code: invalid_state message: >- The operation is unavailable in the current resource or account state. Operational commands are unavailable after cancellation is submitted. retryable: false request_id: req_example meta: request_id: req_example schema_version: 1.4.2 generated_at: '2026-10-23T14:00:00Z' data_status: complete Error412: description: Request failed. Inspect error.code and error.retryable. headers: X-Request-ID: description: AMLOK response correlation identifier. schema: type: string example: req_example content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' examples: version_conflict: summary: version_conflict value: error: code: version_conflict message: If-Match or approved action version is stale. retryable: false request_id: req_example meta: request_id: req_example schema_version: 1.4.2 generated_at: '2026-10-23T14:00:00Z' data_status: complete Error422: description: Request failed. Inspect error.code and error.retryable. headers: X-Request-ID: description: AMLOK response correlation identifier. schema: type: string example: req_example content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' examples: invalid_search_scope: summary: invalid_search_scope value: error: code: invalid_search_scope message: Missing or unsupported jurisdiction/search mode. retryable: false request_id: req_example meta: request_id: req_example schema_version: 1.4.2 generated_at: '2026-10-23T14:00:00Z' data_status: complete invalid_money: summary: invalid_money value: error: code: invalid_money message: >- Invalid decimal, missing required currency or incompatible currency pair. retryable: false request_id: req_example meta: request_id: req_example schema_version: 1.4.2 generated_at: '2026-10-23T14:00:00Z' data_status: complete insufficient_evidence: summary: insufficient_evidence value: error: code: insufficient_evidence message: Required decision or metric prerequisites are missing. retryable: false request_id: req_example meta: request_id: req_example schema_version: 1.4.2 generated_at: '2026-10-23T14:00:00Z' data_status: complete workload_limit_exceeded: summary: workload_limit_exceeded value: error: code: workload_limit_exceeded message: >- The agreed workload limit cannot cover this work. No automatic tier upgrade or surcharge occurs. Contact AMLOK to agree expanded scope. retryable: false request_id: req_example meta: request_id: req_example schema_version: 1.4.2 generated_at: '2026-10-23T14:00:00Z' data_status: complete Error429: description: Request failed. Inspect error.code and error.retryable. headers: X-Request-ID: description: AMLOK response correlation identifier. schema: type: string example: req_example Retry-After: description: >- Delay in seconds or an HTTP-date. The example is illustrative, not a contractual quota. schema: type: string example: '30' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' examples: rate_limited: summary: rate_limited value: error: code: rate_limited message: AMLOK tenant quota or upstream throttle. retryable: true request_id: req_example meta: request_id: req_example schema_version: 1.4.2 generated_at: '2026-10-23T14:00:00Z' data_status: complete Error500: description: Request failed. Inspect error.code and error.retryable. headers: X-Request-ID: description: AMLOK response correlation identifier. schema: type: string example: req_example content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' examples: internal_error: summary: internal_error value: error: code: internal_error message: Unexpected AMLOK processing error. retryable: false request_id: req_example meta: request_id: req_example schema_version: 1.4.2 generated_at: '2026-10-23T14:00:00Z' data_status: complete Error503: description: Request failed. Inspect error.code and error.retryable. headers: X-Request-ID: description: AMLOK response correlation identifier. schema: type: string example: req_example content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' examples: source_unavailable: summary: source_unavailable value: error: code: source_unavailable message: Required source temporarily unavailable. retryable: true request_id: req_example meta: request_id: req_example schema_version: 1.4.2 generated_at: '2026-10-23T14:00:00Z' data_status: complete securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: API key description: >- Server-to-server API key bound to exactly one workspace, institution tenant and environment. No caller-supplied workspace override is accepted. Do not use in public browser code. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.