> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usenexio.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List ledger commands

> Follow the action ledger command by command.

## Behavior

Page with `since_seq`: pass each response's `next_seq` back until it is null. See [Writes and the action ledger](/data-services/writes#read-it-back).


## OpenAPI

````yaml GET /api/v1/records/actions
openapi: 3.1.0
info:
  title: Nexio API
  version: '1.0'
  description: |
    The Nexio public API. Submit runs to configured engines and read their
    results, hold conversations with configured assistants, make authorized
    reads over the planes and families of a connected system of record, and
    manage webhooks and environments.

    Six engine types are registered: comparison, matching, entity_analysis,
    diligence, triage, and opportunity.

    Every route under /api/v1/ requires `Authorization: Bearer <key>`, except
    inbound event ingest (`POST /api/v1/events/ingest/{source_key}`), which
    authenticates each request against its ingest source instead: an
    HMAC-SHA256 signature for `nexio` and `github` sources, or a shared
    authentication code for an `ams360_ons` source. Error
    bodies share the `Error` schema. Call the API from servers only: it sends
    no CORS headers.
  contact:
    email: support@usenexio.com
    url: https://docs.usenexio.com
servers:
  - url: https://api.usenexio.com
    description: >-
      Nexio API. Sandbox or live is chosen by the API key's environment, not by
      the host.
security:
  - BearerAuth: []
tags:
  - name: EngineManagement
    description: >-
      Create, configure, version and manage engines. An engine is a
      configuration of one registered engine type.
  - name: Engines
    description: Engine-scoped endpoints for submitting runs and retrieving results.
  - name: Runs
    description: Retrieve and reconcile submitted runs.
  - name: Records
    description: >-
      Typed, authorized reads over the registered planes and families of a
      connected system of record, and governed writes to the action ledger. The
      generic family read is the core contract.
  - name: Graph
    description: >-
      The organization's data graph: a read-only map of connections and the
      derivations scheduled on them. Node kinds are a closed registry of 16; the
      API serves 14.
  - name: Environments
    description: >-
      The live environment and up to 5 sandbox environments in your org.
      Organization keys only.
  - name: Webhooks
    description: >-
      Manage webhook endpoints that receive terminal run events (run.completed,
      run.failed, run.cancelled) and run corrections (run.superseded).
  - name: Events
    description: >-
      Send inbound events to your organization's event log through an ingest
      source. Source kinds are nexio, github and ams360_ons; a nexio source
      sends event types from your own vocabulary.
  - name: Converse
    description: The raw stateless conversational model turn (caller-owned state).
  - name: Conversations
    description: >-
      Conversation instances (orchestrators over engines) and their managed
      conversations, turns, annotations, evals, and exports.
  - name: Platform
    description: Service health. No key needed.
paths:
  /api/v1/records/actions:
    get:
      tags:
        - Records
      summary: List ledger commands
      description: >-
        The action ledger itself, command by command, oldest first after
        `since_seq`. A `Self` scope sees only commands the acting person
        authored; `All` and `Platform` see the whole ledger. With
        `X-Nexio-Records-Lens` on a `Self` person, the list still shows only the
        caller's own commands.


        Credential: the organization's live API key, or a scoped key with
        `actions:read`.
      operationId: listRecordsActions
      parameters:
        - name: X-Nexio-Acting-Principal
          in: header
          required: true
          description: >-
            The person the request is for, as your identity provider's stable
            user id. Required on this route; without it the request answers 403
            `identity_unmapped`. Narrows what the key reaches.
          schema:
            type: string
        - name: X-Nexio-Acting-Email
          in: header
          required: false
          description: >-
            The acting person's verified sign-in email. The seat is derived from
            it.
          schema:
            type: string
        - name: X-Nexio-Records-Assertion
          in: header
          required: false
          description: >-
            Signed assertion `v1.<unix seconds>.<hex HMAC-SHA256>` over
            `acting_principal|acting_email|reserved|timestamp` (each part
            trimmed, the email lowercased). The third field is reserved: send an
            empty string. The timestamp must be within 5 minutes of the server
            clock, either way. Checked once Nexio enables assertion verification
            for your organization, when it provisions the signing secret; a
            missing or wrong assertion then answers 403 `assertion_invalid` and
            one outside the window 403 `assertion_stale`.
          schema:
            type: string
        - name: X-Nexio-Records-Lens
          in: header
          required: false
          description: >-
            `principal:<id>`: a read-only view of another person's data, honored
            only for a caller whose own scope is All or Platform and ignored for
            anyone else. For such a caller, a value that is not
            `principal:<id>`, or names nobody, answers 400
            `lens_target_unknown`.
          schema:
            type: string
        - name: since_seq
          in: query
          required: false
          description: Return commands with `seq` greater than this. Defaults to 0.
          schema:
            type: integer
            format: int64
            minimum: 0
            default: 0
        - name: limit
          in: query
          required: false
          description: Rows per page. Defaults to 100; values above 500 are treated as 500.
          schema:
            type: integer
            minimum: 1
            default: 100
        - name: family
          in: query
          required: false
          description: >-
            Command family: the part of the command name before the first dot,
            for example `note`, `task` or `status`. Exact match; an unknown
            family returns no rows.
          schema:
            type: string
        - name: connection_id
          in: query
          required: false
          description: >-
            The system-of-record connection to use. Optional when the
            organization has exactly one qualifying connection; required when it
            has several (otherwise 400 `book_connection_ambiguous`). A
            connection that does not exist in the organization answers 404
            `not_found`.
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: One page of ledger rows.
          headers:
            X-Nexio-Engine-Build:
              description: >-
                The engine commit that computed this response, when the build is
                stamped. Key caches on it.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecordsLedgerResponse'
        '400':
          description: >-
            `invalid_request` (`since_seq` negative or not an integer, `limit`
            not a positive integer, `connection_id` not a UUID),
            `lens_target_unknown`, or `book_connection_ambiguous`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: >-
            `insufficient_capability`, `scoped_key_required`, `dataset_denied`,
            `lens_caller_unattributed`, or an identity refusal:
            `identity_unmapped` (including no `X-Nexio-Acting-Principal`),
            `identity_needs_review`, `identity_suspended`, `identity_stale`,
            `scope_unavailable` (including an Office scope),
            `assertion_invalid`, `assertion_stale`, `service_identity_unknown`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: >-
            `not_found`: the named connection does not exist in this
            organization.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: >-
            `book_unavailable`: the connected data cannot be read now to resolve
            the person's access. `details.reason` names the warehouse cause when
            there is one; no reason means no qualifying connection exists yet.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          $ref: '#/components/responses/RateLimited'
        '499':
          $ref: '#/components/responses/ClientClosedRequest'
        '500':
          description: >-
            `internal_error`, or `audit_write_failed` when a lensed read could
            not be audited.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: >
            `book_unavailable` with `details.reason: busy` when the warehouse
            statement queue is full, or `resolve_retry_exhausted`. Retry the
            same request; it is idempotent.


            Also `auth_unavailable`: API key authentication was briefly
            unavailable before the route ran. That cause is transient; retry it
            with backoff.
          headers:
            Retry-After:
              description: >-
                Seconds to wait before retrying. Sent with `book_unavailable`
                reason `busy`.
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '504':
          $ref: '#/components/responses/RequestTimeout'
      security:
        - BearerAuth: []
components:
  schemas:
    RecordsLedgerResponse:
      type: object
      properties:
        serving:
          $ref: '#/components/schemas/RecordsServing'
        duration_ms:
          type: integer
        data:
          type: array
          items:
            $ref: '#/components/schemas/RecordsLedgerRow'
        next_seq:
          type:
            - integer
            - 'null'
          description: >-
            Pass back as `since_seq` for the next page. Null when the page was
            not full; a full last page still carries a value, and the next call
            returns no rows.
        action_seq:
          type: integer
        limit:
          type: integer
          description: Rows returned on this page.
      required:
        - serving
        - duration_ms
        - data
        - next_seq
        - action_seq
        - limit
    Error:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
          description: >
            Stable snake_case error identifier. Safe to match programmatically.

            New codes are added over time; treat an unknown code by its HTTP
            status.


            Known codes include:

            `invalid_request`, `invalid_input`, `unauthorized`,

            `auth_unavailable`, `rate_limited`, `missing_run_id`,

            `invalid_run_id`, `run_not_found`, `invalid_offerings`,

            `missing_input`, `queue_unreachable`, `engine_not_found`,

            `engine_slug_conflict`, `engine_archived`, `instance_not_found`,

            `instance_slug_conflict`, `instance_archived`,

            `instance_follows_canonical`, `instance_not_published`,

            `invalid_engine_type`, `validation_error`, `webhook_not_found`,

            `webhook_limit_exceeded`, `invalid_url`, `invalid_events`,

            `invalid_description`, `invalid_auth_token`,

            `missing_endpoint_id`, `invalid_endpoint_id`,

            `missing_delivery_id`, `invalid_delivery_id`,

            `delivery_not_found`, `delivery_not_resendable`,

            `insufficient_capability`, `engine_version_required`,

            `engine_version_exact_required`, `engine_version_not_found`,

            `engine_version_invalid_format`,

            `engine_version_draft_requires_sandbox_key`,

            `engine_version_none_released`, `test_scenario_sandbox_only`,

            `test_scenario_forbidden`, `test_scenario_exact_version_required`,

            `test_scenario_version_not_supported`, `invalid_test_scenario`,

            `request_bound_exceeded`, `run_cap_exceeded`,

            `scoped_key_required`, `engine_binding_forbidden`,

            `request_timeout`, `internal_error`, `idempotency_key_reused`,

            `invalid_idempotency_key`, `acting_principal_mismatch`,

            `run_requires_acting_principal`, `environment_slug_invalid`,

            `environment_slug_reserved`, `environment_slug_taken`,

            `environment_name_invalid`, `environment_limit_reached`,

            `environment_live_immutable`, `environment_not_found`,

            `environment_in_use`, `environment_operation_failed`,

            `list_environments_failed`, `engine_release_unservable`,

            `engine_config_hash_inconsistent`,

            `engine_config_hash_unavailable`,

            `engine_config_version_unavailable`,

            `engine_version_resolve_failed`,

            `engine_config_version_load_failed`,

            `engine_version_publish_mismatch`,

            `engine_version_schema_change_requires_major`,

            `engine_config_hash_missing`, `engine_config_changed`,

            `invalid_engine_config`, `cold_start_gate_not_met`,

            `cold_start_gate_failed`, `cold_start_gate_regressed`,

            `cancel_run_failed`, `event_id_reused`, `invalid_event_id`,

            `missing_event_id`, `invalid_event_type`, `invalid_payload`,

            `reason_text_too_long`, `reason_taxonomy_version_unknown`,

            `invalid_rating`, `missing_comment`, `invalid_target`,

            `invalid_time_on_task`, `scoped_annotation_required`,

            `missing_instance_slug`, `invalid_instance_config`,

            `invalid_eval_waiver`, `instance_config_hash_missing`,

            `config_changed_during_publish`,

            `scenario_set_changed_during_publish`,

            `conversation_eval_regressed`,

            `conversation_eval_execution_failed`,

            `conversation_eval_gate_unavailable`, `publish_failed`,

            `conversation_not_found`, `conversation_archived`,

            `invalid_cursor`, `message_not_found`, `invalid_turn_request`,

            `message_too_long`, `invalid_tool_result`, `invalid_confirmation`,

            `invalid_edit_target`, `turn_in_progress`, `pending_turn`,

            `turn_state_conflict`, `confirmation_environment_unpinned`,

            `instance_config_missing`, `instance_config_invalid`,

            `instance_model_unavailable`, `guardrail_evaluation_failed`,

            `guardrail_config_invalid`, `invalid_conversation_history`,

            `streaming_unsupported`, `converse_unavailable`, `provider_error`,

            `provider_unavailable`, `unknown_model`, `too_many_messages`,

            `too_many_tools`, `invalid_max_tokens`, `invalid_message_role`,

            `invalid_message`, `invalid_content_block`, `invalid_tool`,

            `attachments_not_enabled`, `attachments_unavailable`,

            `attachment_rejected`, `attachment_too_large`,

            `attachments_too_large`, `too_many_attachments`,

            `attachment_not_accepted`, `attachment_not_found`,

            `attachment_changed`, `attachment_read_failed`,

            `attachment_member_delete`, `attachment_not_reservable`,

            `invalid_offset`, `invalid_turn_id`, `invalid_comment`,

            `invalid_reason`, `invalid_feedback_key`, `turn_not_found`,

            `annotation_not_found`, `annotation_not_promotable`,

            `invalid_eval_scenario`, `conversation_eval_scenario_not_found`,

            `conversation_eval_scenario_cap`,

            `conversation_eval_run_not_found`,

            `conversation_eval_baseline_not_found`,

            `conversation_eval_unavailable`,

            `instance_version_invalid_format`, `instance_version_not_found`,

            `document_class_not_open`, `presign_failed`,

            `markets_directory_unavailable`, `book_unavailable`,

            `book_connection_ambiguous`, `identity_unmapped`,

            `identity_needs_review`, `identity_suspended`, `identity_stale`,

            `scope_unavailable`, `assertion_invalid`, `assertion_stale`,

            `cursor_filter_mismatch`, `cursor_expired`,

            `action_schema_unknown`, `action_payload_invalid`,

            `action_out_of_scope`, `action_list_too_large`,

            `overlay_read_only`, `unsupported_node_type`,

            `acting_principal_required`, `action_denied`,

            `appetite_read_denied`, `approval_required`,

            `catalog_access_denied`, `catalog_connection_ambiguous`,

            `create_webhook_failed`, `dataset_denied`, `delivery_id_reused`,

            `document_type_not_servable`, `document_unclassified`,

            `egress_manifest_version_mismatch`,

            `egress_manifest_version_required`, `event_type_not_allowed`,

            `event_type_reserved`, `execution_confirm_required`,

            `execution_prohibited`, `ingest_source_disabled`,

            `ingest_source_misconfigured`, `ingest_source_not_found`,

            `invalid_acting_assertion`, `invalid_active`,

            `invalid_credentials`, `invalid_payload_mode`,

            `invalid_signature`, `load_run_failed`, `load_solutions_failed`,

            `load_work_items_failed`, `missing_engine_slug`, `not_found`,

            `object_store_unconfigured`, `provider_not_approved`,

            `resolve_retry_exhausted`, `run_lookup_failed`,

            `service_identity_unknown`, `stale_timestamp`, `surface_denied`,

            `unresolved_market_question`, `unsupported_market_filter`.


            The full list with causes and fixes is at

            https://docs.usenexio.com/reference/errors.
        message:
          type: string
          description: Human-readable error message. May change between versions.
        details:
          description: |
            Optional request-specific details. Request-bound failures use the
            `RequestBoundDetails` object. Validation failures may use an array
            of field issues or another documented object.

            `409 environment_in_use` is the one exception to this envelope: it
            carries a top-level `blockers` object (see `EnvironmentInUseError`)
            instead of `details`.
    RecordsServing:
      type: object
      additionalProperties: false
      required:
        - overlay_rev
        - as_of
      properties:
        batch_set_id:
          type: string
          description: >-
            Not sent on current reads; present only on reads served from a
            stored copy.
        binding_id:
          type: string
          description: The connection the read was served from.
        overlay_rev:
          type: integer
          minimum: 0
          description: Always 0 today.
        as_of:
          type: string
          format: date-time
          description: >-
            The request's read time. Every Records read is a current read,
            queried live at request time and not held to a fixed warehouse
            instant. An empty page may carry either the request time or the zero
            time `0001-01-01T00:00:00Z`. The action, note, task, workflow-state
            and edit-intent routes carry the zero time, even when their account
            or policy scope check queries the warehouse.
        read_pin:
          type: string
          format: date-time
          description: >-
            Not sent on Records reads, because no read is held to a fixed
            warehouse instant.
        source:
          type: object
          additionalProperties: false
          required:
            - mode
            - fetched_at
          properties:
            mode:
              type: string
              description: 'query_first: read live from the warehouse at request time.'
            current:
              type: boolean
              description: >-
                `true`: the read queried the current data at request time.
                Source changes can show between separate statements in one
                response and between pages.
            freshness:
              type: string
              enum:
                - current
                - pinned
              description: Not sent on Records reads.
            fetched_at:
              type: string
              format: date-time
              description: The request's read time, the same instant as `as_of`.
            stale_since:
              type: string
              format: date-time
              description: Not sent on Records reads.
        lens:
          type: object
          additionalProperties: false
          required:
            - target
            - display_name
            - scope_kind
          properties:
            target:
              type: string
            display_name:
              type: string
            scope_kind:
              type: string
    RecordsLedgerRow:
      type: object
      properties:
        seq:
          type: integer
        command_id:
          type: string
        actor_principal:
          type: string
        actor_type:
          type: string
        entity_domain:
          type: string
        connection_id:
          type: string
        client_key:
          type: string
        ams360_datasource:
          type: string
          description: >-
            The source system's tenant key for the record (a field of the source
            system).
        policy_id:
          type: string
        app_entity_type:
          type: string
        app_entity_id:
          type: string
        catalog_entity_type:
          type: string
        catalog_id:
          type: string
        command:
          type: string
        schema_rev:
          type: integer
        payload:
          type: object
          additionalProperties: true
        issued_at:
          type: string
          format: date-time
        recorded_at:
          type: string
          format: date-time
      required:
        - seq
        - command_id
        - actor_principal
        - actor_type
        - entity_domain
        - command
        - schema_rev
        - payload
        - recorded_at
  responses:
    Unauthorized:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: unauthorized
            message: Missing or invalid API key
    RateLimited:
      description: Rate limit exceeded. Retry after the window resets.
      headers:
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: rate_limited
            message: Rate limit exceeded
    ClientClosedRequest:
      description: |
        `client_closed_request`: the caller closed the connection before the
        read finished. Nothing reads this body; it exists so the abandoned
        read is recorded as 499 rather than as a server error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: client_closed_request
            message: The client closed the request before the book read finished
    RequestTimeout:
      description: >-
        `request_timeout`: the 30 second route timeout expired before the
        handler answered.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: request_timeout
            message: Request timed out
  headers:
    RetryAfter:
      description: Whole seconds to wait before retrying, at least 1.
      schema:
        type: integer
        minimum: 1
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: >
        Send the key as `Authorization: Bearer <key>`. Two kinds of key exist.


        Organization keys are issued in the portal (Settings, then API keys),

        each bound to one environment, shaped `nx_<environment slug>_<64 hex>`.
        They carry

        no capabilities and pass every capability check, with one exception:

        routes under /api/v1/records, /api/v1/engines/{id}/opportunities,

        /api/v1/graph and /api/v1/catalog/documents accept an

        organization key only when its environment is `live`, and refuse any

        other with 403 `scoped_key_required`. Revocation takes effect within 60

        seconds.


        Scoped keys are issued by Nexio on request, shaped

        `nxsk_v1_<24 hex key id>_<43 character secret>`. Each is bound to one

        org, one environment, a set of engines and a set of capabilities. A

        malformed, unknown or revoked `nxsk_` key fails with 401 and is never

        retried as an organization key. Revocation takes effect on the next

        request. A scoped key without a route's capability gets 403

        `insufficient_capability`; a scoped key not bound to the engine gets 403

        `engine_binding_forbidden`.


        Key-grantable capabilities: `engines:read`, `runs:write`, `runs:read`,

        `runs:defensibility:read`, `runs:test`, `catalog:read`,

        `catalog:documents:read`, `webhooks:manage`, `conversations:use`,

        `conversations:export`, `records:read`, `records:opportunities:run`,

        `actions:write`, `actions:read`, `graph:read`, `records:analyze`.


        Routes that accept organization keys only (every scoped key gets 403

        `insufficient_capability`): environment management, engine create,

        update, configuration and publish, and conversation instance

        authoring. Each operation description names the capability a scoped

        key needs.

````