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); account.owner (account role owner or higher in at least one account; the call is scoped to those accounts); org.member (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_reports
- REST
- POST https://api.containertradehq.com/v1/cap/list_reports
Idempotency: a read: calling again changes nothing
Inputs
| name | type | required | validation |
|---|---|---|---|
| org_id | org_id | optional | tradehq-org-id; 1 to 20 characters One org's reports. A member names their own org; staff and an account owner may leave it out for every org they reach. |
| account_id | account_id | optional | tradehq-account-id One account's orgs. An account owner may name only an account they own. |
| filters | filters | optional | Reports matching every term given. |
| q | text | optional | 1 to 200 characters Words in a report's title or text, case ignored: "already reported?". |
| sort | sort | optional | 1 to 1 items; default [{"key":"reported_at","dir":"desc"}] One sort key and its direction. Newest report first when left out. |
| fields | fields | optional | 1 to any number of items; unique; default ["ticket","org_name","title","kind","filed_via","reporter","reporter_email","impact","private","reported_at","status","status_at","window","note","release_note_url","duplicate_of","duplicate_status","fixed_at","days_to_fix","last_event_at","following","unread"] The fields to answer, from the field groups. All three groups when left out. |
| limit | integer | optional | 1 to 200; default 50 The page size. |
| after | cursor | optional | tradehq-keyset-cursor; up to 1024 characters The previous page's next_after. |
Paginated: cursor_input after · next next_after · page_max 200 · walk_max 10000 · 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": {
"report_id": {
"type": "string",
"pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$",
"format": "uuid",
"description": "The report's id: its ticket's id in the support tracker.",
"x-data-class": "operational"
},
"org_id": {
"type": "string",
"minLength": 1,
"maxLength": 20,
"pattern": "^[A-Za-z0-9_-]{1,20}$",
"format": "tradehq-org-id",
"description": "The org that filed it.",
"x-data-class": "operational"
},
"ticket": {
"type": "string",
"description": "Its reference, CUS-n, as the customer quotes it.",
"x-data-class": "operational"
},
"org_name": {
"type": [
"string",
"null"
],
"description": "That org's name.",
"x-data-class": "operational"
},
"title": {
"type": "string",
"description": "The first line of the reporter's own words.",
"x-data-class": "operational"
},
"kind": {
"type": "string",
"enum": [
"feedback",
"problem",
"question"
],
"description": "Feedback, a problem or a question.",
"x-data-class": "operational"
},
"filed_via": {
"type": "string",
"enum": [
"app",
"email",
"staff"
],
"description": "How it was filed: in the app, by email, or by staff for the customer.",
"x-data-class": "operational"
},
"reporter": {
"anyOf": [
{
"type": [
"object",
"null"
]
},
{
"const": "•••",
"description": "Masked by the caller's data policy."
},
{
"type": "null",
"description": "Denied by the caller's data policy."
}
],
"description": "The member who filed it in the app, {user_id, name}; null when it was filed by email or by staff.",
"x-data-class": "personal"
},
"reporter_email": {
"anyOf": [
{
"type": [
"string",
"null"
]
},
{
"const": "•••",
"description": "Masked by the caller's data policy."
},
{
"type": "null",
"description": "Denied by the caller's data policy."
}
],
"description": "The sender's address, for a report filed by email.",
"x-data-class": "personal"
},
"impact": {
"type": [
"string",
"null"
],
"enum": [
"blocking",
"slowing",
"suggestion",
null
],
"description": "How much it hurts, in the reporter's estimate.",
"x-data-class": "operational"
},
"private": {
"type": "boolean",
"description": "Whether only its reporter and staff see it.",
"x-data-class": "operational"
},
"reported_at": {
"type": "string",
"format": "date-time",
"description": "When it was filed.",
"x-data-class": "operational"
},
"status": {
"type": "string",
"enum": [
"received",
"waiting_on_you",
"planned",
"fixed",
"answered",
"wont_fix",
"duplicate"
],
"description": "Where it stands.",
"x-data-class": "operational"
},
"status_at": {
"type": "string",
"format": "date-time",
"description": "When it reached that status.",
"x-data-class": "operational"
},
"window": {
"type": [
"string",
"null"
],
"enum": [
"next_release",
"this_month",
"later",
null
],
"description": "When a planned report is expected: next release, this month or later; null unless planned.",
"x-data-class": "operational"
},
"note": {
"type": [
"string",
"null"
],
"description": "The latest note written for the customer.",
"x-data-class": "operational"
},
"release_note_url": {
"type": [
"string",
"null"
],
"description": "The customer-facing release note of the fix, when it has one.",
"x-data-class": "operational"
},
"duplicate_of": {
"type": [
"string",
"null"
],
"pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$",
"format": "uuid",
"description": "The report this one duplicates, when that report is this org's and the person asking may see it.",
"x-data-class": "operational"
},
"duplicate_status": {
"type": [
"string",
"null"
],
"enum": [
"received",
"waiting_on_you",
"planned",
"fixed",
"answered",
"wont_fix",
"duplicate",
null
],
"description": "The status of the report this one duplicates.",
"x-data-class": "operational"
},
"fixed_at": {
"type": [
"string",
"null"
],
"format": "date-time",
"description": "When the fix went live for the org.",
"x-data-class": "operational"
},
"days_to_fix": {
"type": [
"integer",
"null"
],
"description": "Calendar days, Pacific time, from the day reported to the day fixed.",
"x-data-class": "operational"
},
"last_event_at": {
"type": [
"string",
"null"
],
"format": "date-time",
"description": "When its timeline last changed.",
"x-data-class": "operational"
},
"following": {
"type": "boolean",
"description": "Whether the person asking follows it.",
"x-data-class": "operational"
},
"unread": {
"type": "boolean",
"description": "Whether it changed since the person asking last saw it.",
"x-data-class": "operational"
}
},
"required": [
"report_id",
"org_id"
],
"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
walk_ceiling_reached· 422 · the cursor walk has answered 10,000 rows, the most one walk answers
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 a report listing; the box reaches it through the intent surface, which serves what MCP serves
- Outbound: a read emits nothing
Events
None emitted.
Related
list_api_keys, list_capability_events, list_granted_capabilities, summarize_reports