summarize_reports · Summarize customer reports

Contract

shape: entity
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: summarize_reports
REST: POST https://api.containertradehq.com/v1/cap/summarize_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?".
period	period	optional	The days counted, {from?, to?}, YYYY-MM-DD and inclusive, Pacific time; every day when left out.

Response

reported · integer · How many reports were reported in the period and match the filters.
by_status · object · Of those, how many stand in each status: every status, zero included.
median_days_to_fix · numbernull · The median calendar days, Pacific time, from reported to fixed, over those fixed; null when none is.
median_days_to_first_response · numbernull · The median calendar days from reported to Trade HQ's first response, over those answered; null when none is.
period · object · The period counted, {from, to}, each null when left open.

Full JSON Schema

{
  "type": "object",
  "properties": {
    "reported": {
      "type": "integer",
      "minimum": 0,
      "description": "How many reports were reported in the period and match the filters.",
      "x-data-class": "operational"
    },
    "by_status": {
      "type": "object",
      "description": "Of those, how many stand in each status: every status, zero included.",
      "x-data-class": "operational"
    },
    "median_days_to_fix": {
      "type": [
        "number",
        "null"
      ],
      "description": "The median calendar days, Pacific time, from reported to fixed, over those fixed; null when none is.",
      "x-data-class": "operational"
    },
    "median_days_to_first_response": {
      "type": [
        "number",
        "null"
      ],
      "description": "The median calendar days from reported to Trade HQ's first response, over those answered; null when none is.",
      "x-data-class": "operational"
    },
    "period": {
      "type": "object",
      "description": "The period counted, {from, to}, each null when left open.",
      "x-data-class": "operational"
    }
  },
  "required": [
    "reported",
    "by_status",
    "median_days_to_fix",
    "median_days_to_first_response",
    "period"
  ],
  "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 a report summary; the box reaches it through the intent surface, which serves what MCP serves
Outbound: a read emits nothing

Events

None emitted.

list_reports