> ## 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 usage record > Read immutable usage charges and correcting reversals. Usage records exist only for actual deductions or their corrections; unfinished work is represented by its processing resource, not a pending credit category. Order by selected time_basis then id. No customer endpoint creates charges. Cancellation stops all further deductions. 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 immutable usage charges and correcting reversals. Usage records exist only for actual deductions or their corrections; unfinished work is represented by its processing resource, not a pending credit category. Order by selected time\_basis then id. No customer endpoint creates charges. Cancellation stops all further deductions. 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/usage/{id} 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/usage/{id}: get: tags: - Reporting summary: Retrieve usage record description: >- Read immutable usage charges and correcting reversals. Usage records exist only for actual deductions or their corrections; unfinished work is represented by its processing resource, not a pending credit category. Order by selected time_basis then id. No customer endpoint creates charges. Cancellation stops all further deductions. 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: WA004 parameters: - name: id in: path required: true description: Authorized resource identifier. schema: type: string example: billing_usage_example - 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/BillingUsage' meta: $ref: '#/components/schemas/ResponseMeta' required: - data - meta examples: synthetic: summary: Synthetic retrieve usage record value: data: id: billing_usage_example object: billing_usage 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 product: insights tier: standard source_resource_id: wfr_example unit: completed_underwriting quantity: '1' unit_rate: '5.00' currency: CAD amount: '5.00' entry_type: charge reverses_usage_id: null status: posted subject_id: biz_example workflow_run_id: wfr_example application_id: app_example input_manifest_id: manifest_example risk_snapshot_id: risk_snapshot_example monitoring_period_id: null occurred_at: '2026-10-23T14:00:00Z' posted_at: '2026-10-23T14:00:00Z' billing_period_start: '2026-10-01T00:00:00Z' billing_period_end: '2026-11-01T00:00:00Z' rate_card_id: billing_rate_card_example ledger_entry_id: billing_credit_entry_example 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/usage/billing_usage_example?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/usage/billing_usage_example?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/usage/billing_usage_example?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: BillingUsage: 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 product: type: string enum: - insights - signal tier: type: string enum: - standard - advanced - complex source_resource_id: type: string minLength: 1 description: >- Workflow-run ID for Insights; borrower/business ID for Signal. Follow workflow_run_id, application_id, input_manifest_id and risk_snapshot_id for underwriting evidence, or monitoring_period_id for the single Signal account-month. unit: type: string enum: - completed_underwriting - active_account_month description: >- Signal counts each active borrower/business once per workspace per month, including change-driven reassessment without an additional Insights charge, regardless of checks, monitoring configurations, facilities or data connections. Cancellation immediately stops further processing and usage deductions. Previously spent credits remain consumed; cancelled unfinished work creates no charge. quantity: type: string pattern: ^(0|[1-9][0-9]*)(\.[0-9]+)?$ unit_rate: type: string pattern: ^(0|[1-9][0-9]*)\.[0-9]{2}$ description: Nonnegative CAD amount, exact decimal string in major units. currency: type: string enum: - CAD amount: type: string pattern: ^-?(0|[1-9][0-9]*)\.[0-9]{2}$ description: >- Signed CAD amount with exactly two decimal places. Negative values represent deductions or reversing adjustments. entry_type: type: string enum: - charge - reversal reverses_usage_id: anyOf: - type: string minLength: 1 - type: 'null' status: type: string enum: - posted subject_id: type: string minLength: 1 workflow_run_id: anyOf: - type: string minLength: 1 - type: 'null' application_id: anyOf: - type: string minLength: 1 - type: 'null' input_manifest_id: anyOf: - type: string minLength: 1 - type: 'null' risk_snapshot_id: anyOf: - type: string minLength: 1 - type: 'null' monitoring_period_id: anyOf: - type: string minLength: 1 - type: 'null' occurred_at: type: string format: date-time posted_at: type: string format: date-time billing_period_start: type: string format: date-time billing_period_end: type: string format: date-time rate_card_id: type: string minLength: 1 ledger_entry_id: type: string minLength: 1 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 - product - tier - source_resource_id - unit - quantity - unit_rate - currency - amount - entry_type - reverses_usage_id - status - subject_id - workflow_run_id - application_id - input_manifest_id - risk_snapshot_id - monitoring_period_id - occurred_at - posted_at - billing_period_start - billing_period_end - rate_card_id - ledger_entry_id - snapshot_id additionalProperties: false allOf: - if: properties: product: const: insights then: properties: unit: const: completed_underwriting workflow_run_id: type: string minLength: 1 input_manifest_id: type: string minLength: 1 risk_snapshot_id: type: string minLength: 1 monitoring_period_id: type: 'null' - if: properties: product: const: signal then: properties: unit: const: active_account_month monitoring_period_id: type: string minLength: 1 - if: properties: entry_type: const: charge then: properties: quantity: const: '1' amount: pattern: ^(0|[1-9][0-9]*)\.[0-9]{2}$ reverses_usage_id: type: 'null' - if: properties: entry_type: const: reversal then: properties: amount: pattern: ^-(0|[1-9][0-9]*)\.[0-9]{2}$ reverses_usage_id: type: string minLength: 1 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.