Book a demo

list_accounts

List accounts

read collection tenant-private since 2026-10-01

Lists accounts, ordered by account id, a page at a time. Filters by a case-insensitive substring of the name. Each account carries its id, name, when it was created and how many orgs belong to it. Staff see every account; naming an org narrows the list to the account that holds it. An org admin reads only the account that holds its own org, named by org id, and is refused any other org and any list that names no org.

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` names; with no `org_id`, unsatisfiable); a deactivated caller is refused first
idempotency
safe
emits
none
MCP tool
list_accounts
REST
POST https://api.containertradehq.com/v1/cap/list_accounts

Idempotency: a read: calling again changes nothing

Inputs

nametyperequiredvalidation
querytextoptional1 to 100 characters
A case-insensitive substring of the account's name.
org_idorg_idoptionaltradehq-org-id; 1 to 20 characters
Only the account that holds this org; an org in no account is an empty page. An org admin names its own org here, and is refused without it.
limitintegeroptional1 to 200; default 50
The page size.
afteraccount_idoptionaltradehq-account-id
The previous page's next_after.

Paginated: next next_after · ceiling not_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": {
          "account_id": {
            "type": "string",
            "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
            "format": "tradehq-account-id",
            "description": "The account's id.",
            "x-data-class": "operational"
          },
          "name": {
            "type": "string",
            "description": "The account's name.",
            "x-data-class": "operational"
          },
          "org_count": {
            "type": "integer",
            "description": "How many orgs belong to it.",
            "x-data-class": "operational"
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "When it was created.",
            "x-data-class": "operational"
          }
        },
        "required": [
          "account_id",
          "name",
          "org_count",
          "created_at"
        ],
        "additionalProperties": false
      }
    },
    "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

not yet declared

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 account listing
  • Outbound: crosses to no counterparty

Events

None emitted.

Related

list_agent_reads, list_audit_events, list_audit_exports, list_orgs, list_unit_access, list_users