---
title: "List tickets and escalations"
method: GET
path: "/tickets"
tags: ["Tickets"]
---

# List tickets and escalations

`GET /tickets`

## Request

- Base URL: `https://platform-api.visitoai.com/m2m/v1`
- URL: `https://platform-api.visitoai.com/m2m/v1/tickets`
- Auth: HTTP bearer

Discover durable work across the connected workspace, including legacy reviews. Filter and paginate rather than reading every conversation. Counts are work items, independent of unread and needsReply. Read get_ticket and lifecycle events before deciding an action; conversation/message evidence requires its existing scopes. Follow all pages with unchanged filters. Lists are live, not frozen snapshots. Pass includeCommerce=true to discover Commerce-backed general tickets, including purchase-only work. source=commerce and purchaseId narrow discovery; current workspace Stripe mode applies. Existing clients omit Commerce by default. Never infer purchase completion from a ticket mutation.

## Query parameters

- `limit` integer
- `cursor` string
- `status` 'pending' | 'in_progress' | 'resolved' | 'cancelled'
- `type` 'ticket' | 'escalation'
- `owner` string
- `propertyId` string
- `channel` 'whatsapp' | 'instagram' | 'messenger' | 'webchat'
- `conversationId` string
- `updatedSince` string, date-time
- `includeCommerce` boolean
- `source` 'commerce' | 'other'
- `purchaseId` string

## Response `200`

Confirmed resource state.

- TicketListResponse
  - `tickets` TicketSummary[], required
    - `ticketId` string, required
    - `tenantId` string, required
    - `conversationId` string
    - `type` 'ticket' | 'escalation', required
    - `status` 'pending' | 'in_progress' | 'resolved' | 'cancelled', required
    - `title` string, required
    - `description` string, required
    - `revision` integer, required
    - `channel` string
    - `contextStatus` 'available' | 'unavailable', required
    - `contact` TicketContact, required
      - `displayName` string
      - `avatarUrl` string
    - `business` TicketBusiness
      - `propertyId` string, required
      - `name` string
    - `assignee` TicketAssignee
      - `operatorId` string, required
      - `name` string
    - `createdAt` string, required
    - `updatedAt` string, required
    - `resolvedAt` string
    - `source` TicketSource, required
      - `kind` 'manual' | 'legacy_review' | 'runtime' | 'agent' | 'commerce', required
      - `messageId` string
      - `eventId` string
      - `purchaseId` string
      - `stripeMode` 'test' | 'live'
      - `reason` string
      - `cycle` integer
    - `permittedActions` string[], required
    - `escalation` TicketEscalation
      - `reasonCode` string, required
      - `capturedFields` object
      - `missingFields` string[]
      - `returnsToAiOnResolve` true, required
      - `ownershipActive` boolean, required
      - `knowledgeGap` TicketKnowledgeGap: Saved knowledge-gap context, loaded only by ticket detail. Requires conversations:read for M2M/MCP. Missing or denied evidence is explicit; this is historical evidence, not a current policy evaluation.
        - `contextStatus` 'available' | 'unavailable' | 'permission_denied', required
        - `schemaVersion` '1.0' | '2.0'
        - `category` string: Usually missing_knowledge, weak_evidence, contradictory_evidence, stale_or_unverifiable_evidence or live_provider_required. Older saved categories remain readable.
        - `sourceCount` integer
        - `sourceTitles` string[]: Up to five recorded source titles, not source contents or proof that every listed source caused the contradiction.
        - `importance` string: Optional legacy diagnostic importance, not a ticket priority.
        - `confidence` 'high' | 'medium': Optional saved legacy confidence.
        - `receiptStatus` 'available' | 'unavailable': Whether a matching detection receipt was read. Does not describe ticket completion.
        - `receipt` TicketKnowledgeGapReceipt
          - `receiptId` string, required
          - `reportedAt` string, date-time, required
          - `behavior` 'report_only' | 'create_handoff', required
          - `disposition` 'reported' | 'handoff_requested' | 'handoff_rejected' | 'handoff_failed', required
    - `commerce` object
      - `contextStatus` 'available' | 'unavailable' | 'permission_denied', required
      - `review` TicketCommerceReview
        - `tenantId` string, required
        - `purchaseId` string, required
        - `reason` string, required
        - `factsKey` string, required
        - `sourceVersion` string, required
        - `asOf` string, required
        - `title` string, required
        - `itemName` string, required
        - `currency` string, required
        - `purchaseKind` string, required
        - `paymentStatus` string, required
        - `fulfillmentStatus` string, required
        - `refundStatus` string, required
        - `bookingStatus` string
        - `outcome` string
        - `sourceReconciledAt` string
        - `stripeMode` 'test' | 'live', required
        - `cycle` integer, required
        - `revision` integer, required
        - `required` boolean, required
        - `amountMinor` integer, required
        - `historical` boolean, required
        - `providerBookingIds` string[], required
        - `permittedActions` string[], required
        - `humanActions` string[], required
        - `reconciliation` TicketCommerceReconciliation
          - `outcome` 'completed_externally' | 'verified_no_action_required', required
          - `reference` string, required
          - `note` string, required
          - `actor` TicketCommerceActor, required
            - `id` string, required
            - `type` 'operator' | 'agent', required
            - `name` string
          - `at` string, required
        - `lastCommand` TicketCommerceCommand
          - `id` string, required
          - `action` 'fulfill' | 'reconcile', required
          - `actor` TicketCommerceActor, required
            - `id` string, required
            - `type` 'operator' | 'agent', required
            - `name` string
          - `at` string, required
        - `source` object, required
          - `conversationId` string
          - `conversationKey` string
          - `channel` string
          - `propertyId` string
        - `bookingConfirmed` boolean, required: True only for successful provider booking state plus required stored provider identifiers; reconciliation alone never sets this.
  - `counts` TicketCounts, required
    - `pending` integer, required
    - `in_progress` integer, required
    - `resolved` integer, required
    - `cancelled` integer, required
  - `hasMore` boolean, required
  - `nextCursor` string, nullable, required
  - `asOf` string, required

## Other responses

- `400`: Invalid request.
- `401`: Authentication required.
- `403`: Required permission missing.
- `404`: Resource unavailable in this workspace.
- `409`: State, revision or idempotency conflict.
- `502`: Reconcile an uncertain escalation request.
- `503`: Capability unavailable.

---

[API](https://skmtc.dev/visitoai/apis/visito-m2m-api.md) - [All operations](https://skmtc.dev/visitoai/apis/visito-m2m-api/llms.txt) - [OpenAPI document](https://skmtc.dev/visitoai/apis/visito-m2m-api/revisions/98377d35c234?raw)