---
title: "List conversation handoffs"
method: GET
path: "/conversations/{conversationId}/handoffs"
tags: ["Conversations"]
---

# List conversation handoffs

`GET /conversations/{conversationId}/handoffs`

## Request

- Base URL: `https://platform-api.visitoai.com/m2m/v1`
- URL: `https://platform-api.visitoai.com/m2m/v1/conversations/{conversationId}/handoffs`
- Auth: HTTP bearer

Use to investigate escalation reasons, captured/missing handoff fields, notification events and handoff/review resolutions for one conversation. Discover conversationId with list_conversations. Action execution receipts are separate in list_action_executions. Requires conversations:read. Returns a paginated combined window of handoff and review cases: default/max 30 total cases, ordered by creation time then stored identity, newest first. Follow nextCursor with the same conversation and limit until hasMore=false. Each case contains its latest five events in chronological order, eventsHasMore and eventsNextCursor for list_conversation_handoff_events. Resolution details are fetched independently of the preview. Captured/missing fields, property/working-hours context and resolution remain available. Cases/events can change during reads; deduplicate identities. Check current conversation handoffStatus/activeHandoffCaseId for current ownership, which may not be on a historical page. Reads never resolve a case or send a notification.

## Path parameters

- `conversationId` string, required

## Query parameters

- `limit` integer
- `cursor` string

## Response `200`

Success

- HandoffHistoryPage
  - `conversationId` string
  - `conversationKey` string
  - `handoffs` object[]
    - `caseId` string
    - `status` 'requested' | 'active' | 'resolved' | 'cancelled'
    - `reasonCode` string
    - `operatorNote` string
    - `requestedAt` string
    - `resolvedAt` string
    - `events` HandoffHistoryEvent[]
      - `eventType` string
      - `actorType` 'ai' | 'system' | 'operator'
      - `at` string, date-time
      - `payload` object
      - `eventId` string
      - `payloadStatus` 'available' | 'not_stored' | 'too_large'
    - `titleKey` string
    - `titleFallback` string
    - `intentId` string
    - `propertyId` string
    - `propertyDisplayName` string
    - `severity` 'hard' | 'soft'
    - `requiredFields` string[]
    - `capturedFields` object
    - `capturedFieldsDisplay` object[]
      - `id` string
      - `label` string
      - `value` string
    - `missingFieldsDisplay` object[]
      - `id` string
      - `label` string
    - `policyVersion` string
    - `handoffAvailability` HandoffAvailability
      - `status` 'within_hours' | 'outside_hours' | 'not_configured'
      - `timezone` string
      - `evaluatedAtLocal` string
      - `currentWindow` object
        - `date` string
        - `day` string
        - `start` string
        - `end` string
      - `nextWindow` object
        - `date` string
        - `day` string
        - `start` string
        - `end` string
    - `channel` 'whatsapp' | 'instagram' | 'messenger' | 'tiktok' | 'webchat' | 'playground'
    - `simulation` boolean
    - `resolution` HandoffHistoryResolution
      - `operatorId` string
      - `operatorName` string
      - `operatorEmail` string
      - `resolutionNote` string
      - `resolvedAt` string, date-time
    - `eventsHasMore` boolean
    - `eventsNextCursor` string, nullable: Cursor for older events via list_conversation_handoff_events. Uses event limit 50; pass without limit or with 50.
    - `resolutionDetailsStatus` 'available' | 'not_stored' | 'too_large'
  - `reviews` object[]
    - `caseId` string
    - `status` 'requested' | 'resolved' | 'cancelled'
    - `reasonCode` string
    - `note` string
    - `requestedByOperatorId` string
    - `requestedByOperatorName` string
    - `assignedOperatorId` string
    - `assignedOperatorName` string
    - `requestedAt` string, date-time
    - `resolvedAt` string, date-time
    - `resolution` HandoffHistoryResolution
      - `operatorId` string
      - `operatorName` string
      - `operatorEmail` string
      - `resolutionNote` string
      - `resolvedAt` string, date-time
    - `events` HandoffHistoryEvent[]
      - `eventType` string
      - `actorType` 'ai' | 'system' | 'operator'
      - `at` string, date-time
      - `payload` object
      - `eventId` string
      - `payloadStatus` 'available' | 'not_stored' | 'too_large'
    - `eventsHasMore` boolean
    - `eventsNextCursor` string, nullable: Cursor for older events via list_conversation_handoff_events. Uses event limit 50; pass without limit or with 50.
    - `resolutionDetailsStatus` 'available' | 'not_stored' | 'too_large'
  - `limit` integer, required
  - `hasMore` boolean, required
  - `nextCursor` string, nullable, required

## Other responses

- `400`: Invalid, wrong-business/conversation/kind cursor, changed limit or unknown query
- `413`: History response or stored case metadata exceeds its read budget
- `default`: Structured error

---

[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)