> ## 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 monitoring periods

> Signal charges the full agreed monthly rate once per borrower/business/workspace at 00:00 UTC on the first day of the month, before monitoring proceeds. First activation during a month charges the full monthly rate immediately, without proration; the next charge is at the next month boundary. Repeated monitor creation, pauses, resumes, checks and reassessments do not add charges in an already paid period. Insufficient credits block monitoring without a debit or debt; funding resumes only the current period after its single successful charge, without charging missed inactive months. User-paused monitoring remains paused until the user resumes it. Account cancellation stops processing and all further deductions immediately. Read one shared record per subject/month, including its charge and workload references. Periods are immutable in identity; current status and charged_at reflect activation. API reads never create a charge.

**Required scope:** `monitoring:read`

Signal charges the full agreed monthly rate once per borrower/business/workspace at 00:00 UTC on the first day of the month, before monitoring proceeds. First activation during a month charges the full monthly rate immediately, without proration; the next charge is at the next month boundary. Repeated monitor creation, pauses, resumes, checks and reassessments do not add charges in an already paid period. Insufficient credits block monitoring without a debit or debt; funding resumes only the current period after its single successful charge, without charging missed inactive months. User-paused monitoring remains paused until the user resumes it. Account cancellation stops processing and all further deductions immediately. Read one shared record per subject/month, including its charge and workload references. Periods are immutable in identity; current status and charged\_at reflect activation. API reads never create a charge.

[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/monitoring-periods
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/monitoring-periods:
    get:
      tags:
        - Risk
      summary: List monitoring periods
      description: >-
        Signal charges the full agreed monthly rate once per
        borrower/business/workspace at 00:00 UTC on the first day of the month,
        before monitoring proceeds. First activation during a month charges the
        full monthly rate immediately, without proration; the next charge is at
        the next month boundary. Repeated monitor creation, pauses, resumes,
        checks and reassessments do not add charges in an already paid period.
        Insufficient credits block monitoring without a debit or debt; funding
        resumes only the current period after its single successful charge,
        without charging missed inactive months. User-paused monitoring remains
        paused until the user resumes it. Account cancellation stops processing
        and all further deductions immediately. Read one shared record per
        subject/month, including its charge and workload references. Periods are
        immutable in identity; current status and charged_at reflect activation.
        API reads never create a charge.
      operationId: EN003
      parameters:
        - name: subject_id
          in: query
          required: false
          description: Authorized borrower/business.
          schema:
            type: string
          example: biz_example
        - name: period_start
          in: query
          required: false
          description: Inclusive UTC period-start boundary.
          schema:
            type: string
            format: date-time
        - name: period_end
          in: query
          required: false
          description: Exclusive UTC period-start boundary.
          schema:
            type: string
            format: date-time
        - name: limit
          in: query
          required: false
          description: Default 100; maximum 200.
          schema:
            type: integer
            minimum: 1
            maximum: 200
          example: 100
        - name: cursor
          in: query
          required: false
          description: Opaque continuation bound to the original filters and snapshot.
          schema:
            type: string
      responses:
        '200':
          description: Authorized response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/MonitoringPeriod'
                  page:
                    $ref: '#/components/schemas/Page'
                  meta:
                    $ref: '#/components/schemas/ResponseMeta'
                required:
                  - data
                  - page
                  - meta
              examples:
                synthetic:
                  value:
                    data:
                      - id: monitoring_period_example
                        object: monitoring_period
                        workspace_id: wsp_example
                        subject_id: biz_example
                        period_start: '2026-10-01T00:00:00Z'
                        period_end: '2026-11-01T00:00:00Z'
                        first_activated_at: '2026-10-01T00:00:00Z'
                        charged_at: '2026-10-01T00:00:00Z'
                        billing_usage_id: billing_usage_signal
                        status: active
                        workload_id: workload_signal_example
                        baseline_snapshot_id: rsk_baseline
                        rate_card_id: billing_rate_card_example
                        tier: standard
                        blocked_reason: null
                    page:
                      next_cursor: null
                      has_more: false
                      limit: 100
                    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'
        '410':
          $ref: '#/components/responses/Error410'
        '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/monitoring-periods?subject_id=biz_example&limit=100" \
              --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/monitoring-periods?subject_id=biz_example&limit=100",
                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/monitoring-periods?subject_id=biz_example&limit=100", {
              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:
    MonitoringPeriod:
      type: object
      properties:
        id:
          type: string
          minLength: 1
        object:
          const: monitoring_period
          type: string
        workspace_id:
          type: string
          minLength: 1
        subject_id:
          type: string
          minLength: 1
        period_start:
          type: string
          format: date-time
        period_end:
          type: string
          format: date-time
        first_activated_at:
          type: string
          format: date-time
        charged_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
        billing_usage_id:
          anyOf:
            - type: string
              minLength: 1
            - type: 'null'
        status:
          type: string
          enum:
            - active
            - paused
            - blocked
            - unfunded
            - cancelled
        workload_id:
          type: string
          minLength: 1
        baseline_snapshot_id:
          type: string
          minLength: 1
        rate_card_id:
          type: string
          minLength: 1
        tier:
          type: string
          enum:
            - standard
            - advanced
            - complex
        blocked_reason:
          anyOf:
            - type: string
              enum:
                - insufficient_credits
                - workload_limit_exceeded
                - missing_evidence
                - consent_unavailable
            - type: 'null'
      required:
        - id
        - object
        - workspace_id
        - subject_id
        - period_start
        - period_end
        - first_activated_at
        - charged_at
        - billing_usage_id
        - status
        - workload_id
        - baseline_snapshot_id
        - rate_card_id
        - tier
        - blocked_reason
      additionalProperties: false
    Page:
      type: object
      properties:
        next_cursor:
          anyOf:
            - type: string
            - type: 'null'
          description: Opaque cursor for subsequent page; null after final page.
        has_more:
          type: boolean
          description: Whether more authorized records remain.
        limit:
          type: integer
          description: Applied result limit, from 1 to 200 in this contract.
          minimum: 1
          maximum: 200
      required:
        - has_more
        - limit
    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
    Error410:
      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:
            cursor_expired:
              summary: cursor_expired
              value:
                error:
                  code: cursor_expired
                  message: >-
                    The synchronization cursor has expired. Begin a new
                    synchronization checkpoint and rebuild the collection
                    snapshot.
                  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.