> ## 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.

# List billing usage

> Read what was charged, for which borrower and product, with historical rate, tier, workload and links to the wallet transaction and assessment. Signal combines a borrower across deals once per workspace/month.

Read what was charged, for which borrower and product, with historical rate, tier, workload and links to the wallet transaction and assessment. Signal combines a borrower across deals once per workspace/month. All IDs and cursors must belong to the authorized workspace and environment. Required scope: billing:read. Owner authority is required. Related reads can pin snapshot\_id from billing summary to reconcile the same as-of state; expired snapshots return 410, never a silent refresh.

Examples use synthetic IDs. Replace them with values returned by your environment.


## OpenAPI

````yaml openapi/amlok.json GET /v1/billing/usage
openapi: 3.1.0
info:
  title: AMLOK API
  version: 1.0.0
  description: >-
    AMLOK API: borrower connections, Insights origination, immutable risk
    packages and Signal monitoring. Use your institution-issued API origin.
servers: []
security:
  - BearerAuth: []
paths:
  /v1/billing/usage:
    get:
      tags:
        - Billing
      summary: List billing usage
      description: >-
        Read what was charged, for which borrower and product, with historical
        rate, tier, workload and links to the wallet transaction and assessment.
        Signal combines a borrower across deals once per workspace/month. All
        IDs and cursors must belong to the authorized workspace and environment.
        Required scope: billing:read. Owner authority is required. Related reads
        can pin snapshot_id from billing summary to reconcile the same as-of
        state; expired snapshots return 410, never a silent refresh.
      operationId: listBillingUsage
      parameters:
        - name: cursor
          in: query
          required: false
          schema:
            type: string
            minLength: 1
          description: cursor
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 25
          description: limit
        - name: borrower_id
          in: query
          required: false
          schema:
            type: string
            minLength: 1
          description: borrower id
        - name: product
          in: query
          required: false
          schema:
            type: string
            enum:
              - insights
              - signal
          description: product
        - name: origination_id
          in: query
          required: false
          schema:
            type: string
            minLength: 1
          description: origination id
        - name: monitor_id
          in: query
          required: false
          schema:
            type: string
            minLength: 1
          description: monitor id
        - name: charged_from
          in: query
          required: false
          schema:
            type: string
            format: date-time
          description: >-
            charged from. UTC ranges are inclusive from and exclusive to; reject
            to <= from.
        - name: charged_to
          in: query
          required: false
          schema:
            type: string
            format: date-time
          description: >-
            charged to. UTC ranges are inclusive from and exclusive to; reject
            to <= from.
        - name: snapshot_id
          in: query
          required: false
          schema:
            type: string
            minLength: 1
          description: snapshot id
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/BillingUsage'
                  meta:
                    $ref: '#/components/schemas/Meta'
                  page:
                    $ref: '#/components/schemas/Page'
                required:
                  - data
                  - meta
                  - page
                additionalProperties: false
              example:
                data:
                  - id: usage_synthetic
                    snapshot_id: snap_synthetic
                    borrower_id: bor_synthetic
                    product: insights
                    origination_id: orgn_synthetic
                    monitor_ids: []
                    risk_package_ids:
                      - rp_synthetic
                    period:
                      start: '2026-11-06T00:00:00Z'
                      end: '2026-11-07T00:00:00Z'
                    charged_at: '2026-11-06T12:00:00Z'
                    tier: standard
                    quantity: 1
                    unit_rate: '40.00'
                    amount: '40.00'
                    currency: CAD
                    rate_card_id: rate_synthetic
                    rate_version: synthetic-1
                    transaction_id: txn_usage_synthetic
                    workload:
                      bank_accounts: 1
                      business_systems: 2
                      records: 1500
                      record_counting_basis: per_underwriting
                meta:
                  request_id: req_synthetic
                  schema_version: 1.0.0
                  environment: sandbox
                page:
                  next_cursor: null
                  has_more: false
                  snapshot_id: snap_synthetic
                  expires_at: '2026-11-06T13:00:00Z'
          headers:
            X-Request-ID:
              schema:
                type: string
                minLength: 1
              description: Same request ID as meta.request_id or error.request_id.
        '400':
          description: >-
            Inspect structured error; retry only when retryable. 429 and 503 can
            include Retry-After.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    $ref: '#/components/schemas/Error'
                required:
                  - error
                additionalProperties: false
              example:
                error:
                  code: validation_error
                  message: Validation error.
                  retryable: false
                  request_id: req_synthetic
                  field: null
          headers:
            X-Request-ID:
              schema:
                type: string
                minLength: 1
              description: Same request ID as meta.request_id or error.request_id.
        '401':
          description: >-
            Inspect structured error; retry only when retryable. 429 and 503 can
            include Retry-After.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    $ref: '#/components/schemas/Error'
                required:
                  - error
                additionalProperties: false
              example:
                error:
                  code: unauthenticated
                  message: Unauthenticated.
                  retryable: false
                  request_id: req_synthetic
                  field: null
          headers:
            X-Request-ID:
              schema:
                type: string
                minLength: 1
              description: Same request ID as meta.request_id or error.request_id.
        '403':
          description: >-
            Inspect structured error; retry only when retryable. 429 and 503 can
            include Retry-After.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    $ref: '#/components/schemas/Error'
                required:
                  - error
                additionalProperties: false
              example:
                error:
                  code: forbidden
                  message: Forbidden.
                  retryable: false
                  request_id: req_synthetic
                  field: null
          headers:
            X-Request-ID:
              schema:
                type: string
                minLength: 1
              description: Same request ID as meta.request_id or error.request_id.
        '404':
          description: >-
            Inspect structured error; retry only when retryable. 429 and 503 can
            include Retry-After.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    $ref: '#/components/schemas/Error'
                required:
                  - error
                additionalProperties: false
              example:
                error:
                  code: not_found
                  message: Not found.
                  retryable: false
                  request_id: req_synthetic
                  field: null
          headers:
            X-Request-ID:
              schema:
                type: string
                minLength: 1
              description: Same request ID as meta.request_id or error.request_id.
        '409':
          description: >-
            Inspect structured error; retry only when retryable. 429 and 503 can
            include Retry-After.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    $ref: '#/components/schemas/Error'
                required:
                  - error
                additionalProperties: false
              example:
                error:
                  code: invalid_state
                  message: Invalid state.
                  retryable: false
                  request_id: req_synthetic
                  field: null
          headers:
            X-Request-ID:
              schema:
                type: string
                minLength: 1
              description: Same request ID as meta.request_id or error.request_id.
        '410':
          description: >-
            Inspect structured error; retry only when retryable. 429 and 503 can
            include Retry-After.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    $ref: '#/components/schemas/Error'
                required:
                  - error
                additionalProperties: false
              example:
                error:
                  code: cursor_expired
                  message: Cursor expired.
                  retryable: false
                  request_id: req_synthetic
                  field: null
          headers:
            X-Request-ID:
              schema:
                type: string
                minLength: 1
              description: Same request ID as meta.request_id or error.request_id.
        '429':
          description: >-
            Inspect structured error; retry only when retryable. 429 and 503 can
            include Retry-After.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    $ref: '#/components/schemas/Error'
                required:
                  - error
                additionalProperties: false
              example:
                error:
                  code: rate_limited
                  message: Rate limited.
                  retryable: true
                  request_id: req_synthetic
                  field: null
          headers:
            Retry-After:
              description: Minimum delay in seconds before retry.
              schema:
                type: integer
                minimum: 0
            X-Request-ID:
              schema:
                type: string
                minLength: 1
              description: Same request ID as meta.request_id or error.request_id.
        '503':
          description: >-
            Inspect structured error; retry only when retryable. 429 and 503 can
            include Retry-After.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    $ref: '#/components/schemas/Error'
                required:
                  - error
                additionalProperties: false
              example:
                error:
                  code: temporarily_unavailable
                  message: Temporarily unavailable.
                  retryable: true
                  request_id: req_synthetic
                  field: null
          headers:
            Retry-After:
              description: Minimum delay in seconds before retry.
              schema:
                type: integer
                minimum: 0
            X-Request-ID:
              schema:
                type: string
                minLength: 1
              description: Same request ID as meta.request_id or error.request_id.
      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" \
              --header "Authorization: Bearer ${AMLOK_API_KEY}" \
              --header 'Accept: application/json'
        - lang: Python
          source: >
            import os

            import requests


            headers = {'Accept': 'application/json'}

            headers["Authorization"] = "Bearer " + os.environ["AMLOK_API_KEY"]

            response = requests.request('GET', os.environ["AMLOK_API_BASE_URL"]
            + '/v1/billing/usage', headers=headers, timeout=30,
            allow_redirects=False)

            response.raise_for_status()

            print(response.json())
        - lang: JavaScript
          source: >
            const headers = {"Accept": "application/json"};

            headers.Authorization = `Bearer ${process.env.AMLOK_API_KEY}`;

            const response = await fetch(process.env.AMLOK_API_BASE_URL +
            "/v1/billing/usage", {
              method: "GET", headers, redirect: "error", signal: AbortSignal.timeout(30000)
            });

            if (!response.ok) throw new Error(`HTTP ${response.status}: ${await
            response.text()}`);

            console.log(await response.json());
components:
  schemas:
    BillingUsage:
      type: object
      properties:
        id:
          type: string
          minLength: 1
          description: >-
            Stable usage charge ID, also referenced by risk-package
            billing_usage_id.
        snapshot_id:
          type: string
          minLength: 1
          description: Billing snapshot used for this read.
        borrower_id:
          type: string
          minLength: 1
          description: Opaque ID within the authorized workspace and environment.
        product:
          type: string
          enum:
            - insights
            - signal
          description: >-
            Insights underwriting or Signal monitoring; included stages are not
            separately billed.
        origination_id:
          anyOf:
            - type: string
              minLength: 1
              description: Opaque ID within the authorized workspace and environment.
            - type: 'null'
          description: Charged origination for Insights; null for a Signal monthly charge.
        monitor_ids:
          type: array
          items:
            type: string
            minLength: 1
            description: Opaque ID within the authorized workspace and environment.
          uniqueItems: true
          description: >-
            Monitored deals represented by a combined Signal borrower/month
            charge.
        risk_package_ids:
          type: array
          items:
            type: string
            minLength: 1
            description: Opaque ID within the authorized workspace and environment.
          uniqueItems: true
          description: Published results associated with this charge.
        period:
          $ref: '#/components/schemas/Window'
          description: UTC half-open service interval for this usage.
        charged_at:
          type: string
          minLength: 1
          format: date-time
          description: UTC time the charge was posted.
        tier:
          type: string
          enum:
            - standard
            - advanced
            - complex
          description: Historical workload tier determining the agreed unit rate.
        quantity:
          type: integer
          minimum: 1
          description: Billed units for this immutable charge.
        unit_rate:
          type: string
          minLength: 1
          pattern: ^(?:0|[1-9][0-9]*)\.[0-9]{2}$
          description: Actual effective CAD unit rate after two-decimal half-up rounding.
        amount:
          type: string
          minLength: 1
          pattern: ^(?:0|[1-9][0-9]*)\.[0-9]{2}$
          description: >-
            Positive CAD cost: quantity times rounded unit_rate, rounded half-up
            to two decimals.
        currency:
          const: CAD
          description: >-
            Currency for BillingUsage. Constraints, requiredness and allowed
            values are defined by this schema.
        rate_card_id:
          type: string
          minLength: 1
          description: Historical agreed rate-card reference.
        rate_version:
          type: string
          minLength: 1
          description: Exact historical pricing version, not the current rate.
        transaction_id:
          type: string
          minLength: 1
          description: Posted negative usage ledger entry for this charge.
        workload:
          type: object
          properties:
            bank_accounts:
              type: integer
              minimum: 0
            business_systems:
              type: integer
              minimum: 0
            records:
              type: integer
              minimum: 0
            record_counting_basis:
              type: string
              enum:
                - per_underwriting
                - new_records_per_month
          required:
            - bank_accounts
            - business_systems
            - records
            - record_counting_basis
          additionalProperties: false
          description: >-
            Counts used to explain the charged tier, distinct from the billed
            quantity.
      required:
        - id
        - snapshot_id
        - borrower_id
        - product
        - origination_id
        - monitor_ids
        - risk_package_ids
        - period
        - charged_at
        - tier
        - quantity
        - unit_rate
        - amount
        - currency
        - rate_card_id
        - rate_version
        - transaction_id
        - workload
      additionalProperties: false
      description: >-
        Immutable charge explanation. Amount is the positive cost; the linked
        ledger usage transaction is negative. Rates are the actual historical
        agreed rates, never current estimates. Signal is one
        borrower/workspace/month across all monitored deals; included
        reassessments add no Insights charge.
      allOf:
        - if:
            properties:
              product:
                const: insights
          then:
            properties:
              origination_id:
                type: string
                minLength: 1
                description: Opaque ID within the authorized workspace and environment.
              workload:
                properties:
                  record_counting_basis:
                    const: per_underwriting
          else:
            properties:
              origination_id:
                type: 'null'
              workload:
                properties:
                  record_counting_basis:
                    const: new_records_per_month
    Meta:
      type: object
      properties:
        request_id:
          type: string
          minLength: 1
          description: >-
            Opaque identifier, authorized within the API key workspace and
            environment.
        schema_version:
          type: string
          minLength: 1
          description: >-
            Schema version for Meta. Constraints, requiredness and allowed
            values are defined by this schema.
        environment:
          type: string
          enum:
            - sandbox
            - live
          description: >-
            Environment for Meta. Constraints, requiredness and allowed values
            are defined by this schema.
      required:
        - request_id
        - schema_version
        - environment
      additionalProperties: false
    Page:
      type: object
      properties:
        next_cursor:
          anyOf:
            - type: string
              minLength: 1
            - type: 'null'
          description: >-
            Next cursor for Page. Constraints, requiredness and allowed values
            are defined by this schema.
        has_more:
          type: boolean
          description: >-
            Has more for Page. Constraints, requiredness and allowed values are
            defined by this schema.
        snapshot_id:
          type: string
          minLength: 1
          description: >-
            Opaque identifier, authorized within the API key workspace and
            environment.
        expires_at:
          type: string
          minLength: 1
          description: >-
            Snapshot expiry. After expiry, respond 410 and restart with a new
            snapshot; never continue on a new snapshot silently.
          format: date-time
      required:
        - next_cursor
        - has_more
        - snapshot_id
        - expires_at
      additionalProperties: false
      description: >-
        Opaque cursor binds filters, authorization and a stable snapshot.
        Expired cursors return 410; never silently restart.
    Error:
      type: object
      properties:
        code:
          type: string
          enum:
            - validation_error
            - unauthenticated
            - forbidden
            - not_found
            - invalid_state
            - idempotency_conflict
            - insufficient_credits
            - precondition_failed
            - cursor_expired
            - rate_limited
            - temporarily_unavailable
            - deal_snapshot_conflict
            - payload_too_large
            - unsupported_media_type
            - document_rejected
            - processing_failed
            - session_expired
            - consent_purpose_missing
            - sandbox_only
            - scenario_not_available
            - idempotency_result_expired
          description: >-
            Code for Error. Constraints, requiredness and allowed values are
            defined by this schema.
        message:
          type: string
          minLength: 1
          description: >-
            Message for Error. Constraints, requiredness and allowed values are
            defined by this schema.
        retryable:
          type: boolean
          description: >-
            Retryable for Error. Constraints, requiredness and allowed values
            are defined by this schema.
        request_id:
          type: string
          minLength: 1
          description: >-
            Opaque identifier, authorized within the API key workspace and
            environment.
        field:
          anyOf:
            - type: string
              minLength: 1
            - type: 'null'
          description: >-
            Field for Error. Constraints, requiredness and allowed values are
            defined by this schema.
      required:
        - code
        - message
        - retryable
        - request_id
        - field
      additionalProperties: false
    Window:
      type: object
      properties:
        start:
          type: string
          minLength: 1
          format: date-time
          description: >-
            Start for Window. Constraints, requiredness and allowed values are
            defined by this schema.
        end:
          type: string
          minLength: 1
          format: date-time
          description: >-
            End for Window. Constraints, requiredness and allowed values are
            defined by this schema.
      required:
        - start
        - end
      additionalProperties: false
      description: UTC interval [start, end). The server rejects end <= start.
  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.