Book a demo

list_agent_reads

List agent reads

read collection tenant-private since 2026-10-01

Lists what Trade HQ's agents read of the org's business content, newest first: each read's agent, the records it read (purchase orders, invoices, orders), the kinds of fields it was answered, those masked and those your own data policies deny, how many records, and the purpose it stated, a ticket when there is one. Bank and card numbers are only ever shown to an agent as their last four.

Contract

shape
collection
authority
read
evidence
none
subscription
false
permission
any one of: staff.read (the staff role staff_read held in the Internal org, tradehq_role.staff_role); org.admin (carried by the caller's role template in the org `org_id`); account.owner (account role owner or higher in the account of the org `org_id`); a deactivated caller is refused first
idempotency
safe
emits
none
MCP tool
list_agent_reads
REST
POST https://api.containertradehq.com/v1/cap/list_agent_reads

Idempotency: a read: calling again changes nothing

Inputs

nametyperequiredvalidation
org_idorg_idrequiredtradehq-org-id; 1 to 20 characters
The org whose agent reads to list.
limitintegeroptional1 to 200; default 50
How many of the newest reads to answer.

Paginated: next next_after · page_max 200 · walk_max 200 · ceiling declared

Response

  • items · object[]
  • next_after · stringnull · Pass as `after` for the next page; null on the last one.
Full JSON Schema 
{
  "type": "object",
  "properties": {
    "items": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "read_id": {
            "type": "string",
            "description": "The read's id.",
            "x-data-class": "operational"
          },
          "at": {
            "type": "string",
            "format": "date-time",
            "description": "When it was read.",
            "x-data-class": "operational"
          },
          "actor": {
            "type": "string",
            "description": "The agent that read it: its broker role, <name>@<context>.",
            "x-data-class": "operational"
          },
          "family": {
            "type": "string",
            "description": "What it read: purchase_orders, sales_orders, order_line_items, invoices, inbound_documents and so on.",
            "x-data-class": "operational"
          },
          "relation": {
            "type": "string",
            "description": "The table it read.",
            "x-data-class": "operational"
          },
          "classes_read": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "The kinds of field it was answered: commercial, financial, personal, operational.",
            "x-data-class": "operational"
          },
          "classes_masked": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "The kinds answered masked, because one of the org's own data policies masks them.",
            "x-data-class": "operational"
          },
          "classes_denied": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "The kinds never read, because one of the org's own data policies denies them.",
            "x-data-class": "operational"
          },
          "filter_columns": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "The fields it filtered on, never their values.",
            "x-data-class": "operational"
          },
          "record_count": {
            "type": "integer",
            "minimum": 0,
            "description": "How many records it was answered.",
            "x-data-class": "operational"
          },
          "purpose": {
            "type": "string",
            "description": "Why it read them, as the agent stated it: a ticket when there is one.",
            "x-data-class": "operational"
          },
          "refused": {
            "type": [
              "string",
              "null"
            ],
            "description": "Why the read was refused, when it was: it filtered on a kind of field your own data policies mask (filter_on_masked_class) or deny (class_restricted_by_customer). Nothing was read.",
            "x-data-class": "operational"
          }
        },
        "required": [
          "read_id",
          "at",
          "actor",
          "family",
          "relation",
          "classes_read",
          "classes_masked",
          "classes_denied",
          "filter_columns",
          "record_count",
          "purpose",
          "refused"
        ],
        "additionalProperties": false
      },
      "maxItems": 200
    },
    "next_after": {
      "type": [
        "string",
        "null"
      ],
      "description": "Pass as `after` for the next page; null on the last one."
    }
  },
  "required": [
    "items",
    "next_after"
  ],
  "additionalProperties": false
}

Refusals

The platform refusals apply to every call: version, authentication, authority, validation and rate limits, each in the same envelope.

Surfaces

DesktopF
MobileF
APIF
MCPF
VoiceD4
PushN
OneBoxN
OutboundN
  • Voice: degraded: visualization
  • Push: emits nothing
  • OneBox: no document originates an agent read
  • Outbound: crosses to no counterparty

Events

None emitted.

Related

list_accounts, list_audit_events, list_audit_exports, list_orgs, list_unit_access, list_users