# List Handoffs

> Page<HandoffAdmin & { conversation_id }> (newest first).

Source: https://shopassist.coec.dk/docs/api/reference/conversations/list-handoffs · Updated 2026-11-03

`GET /v1/stores/{store_id}/handoffs`

- Scope: `conversations:read`
- Rate limit: 600 requests/min per API key (test keys: 60/min)

`Page<HandoffAdmin & { conversation_id }>` (newest first).

## Parameters [#parameters]

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `store_id` | path | `string` | yes |  |
| `limit` | query | `integer` | no | Page size |
| `cursor` | query | `string \| null` | no | Cursor from the previous page |

## Example request [#example-request]

```bash
curl -X GET "https://api.shopassist.coec.dk/v1/stores/sto_01j8000000e008000000000000/handoffs" \
  -H "Authorization: Bearer $SHOPASSIST_API_KEY"
```

## Response 200 (Page_HandoffAdminListItem_) [#response]

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | `HandoffAdminListItem[]` | yes |  |
| `data[].accepted_at` | `string \| null` | yes | format date-time |
| `data[].agent` | `AgentRef \| null` | yes |  |
| `data[].agent.display_name` | `string` | yes |  |
| `data[].conversation_id` | `string` | yes | pattern `^conv_[0-9a-hjkmnp-tv-z]{26}$` |
| `data[].delivered_at` | `string \| null` | yes | format date-time |
| `data[].expected_wait_seconds` | `integer \| null` | yes |  |
| `data[].id` | `string` | yes | pattern `^hof_[0-9a-hjkmnp-tv-z]{26}$` |
| `data[].message` | `string` | yes | Localized shopper-facing status text |
| `data[].reason` | `string (enum)` | yes | one of shopper_request, ai_escalation, action_request, policy, repeated_failure, error, outside_hours, quota_block, limit_reached |
| `data[].requested_at` | `string` | yes | format date-time |
| `data[].requested_by` | `"shopper" \| "ai" \| "agent" \| "system"` | yes |  |
| `data[].shopper` | `HandoffShopper` | yes | `HandoffAdmin.shopper` (`platform_customer_id` only for `identity_level = customer`). |
| `data[].shopper.email` | `string \| null` | yes |  |
| `data[].shopper.email_verified` | `boolean` | yes |  |
| `data[].shopper.identity_level` | `"guest" \| "order_lookup" \| "order_otp" \| "customer"` | yes |  |
| `data[].shopper.name` | `string \| null` | yes |  |
| `data[].shopper.platform_customer_id` | `string \| null` | yes |  |
| `data[].state` | `"requested" \| "waiting_for_agent" \| "live" \| "delivered_offline" \| "failed" \| "resolved"` | yes |  |
| `data[].status` | `string (enum)` | yes | one of requested, waiting_for_agent, live, delivering, delivered, failed, resolved, cancelled |
| `data[].summary` | `string \| null` | yes |  |
| `data[].target` | `"live_chat" \| "email" \| "helpdesk" \| null` | yes |  |
| `data[].targets` | `HandoffTargetView[]` | yes |  |
| `data[].targets[].external_url` | `string \| null` | yes | format uri · ≤ 2048 characters |
| `data[].targets[].integration_id` | `string \| null` | yes | pattern `^int_[0-9a-hjkmnp-tv-z]{26}$` |
| `data[].targets[].last_error` | `string \| null` | yes |  |
| `data[].targets[].status` | `"pending" \| "delivered" \| "failed" \| "skipped"` | yes |  |
| `data[].targets[].type` | `string` | yes |  |
| `has_more` | `boolean` | yes |  |
| `next_cursor` | `string \| null` | yes | Opaque cursor for the next page; null on the last page |

```json
{
  "data": [
    {
      "expected_wait_seconds": 120,
      "id": "hof_01j8000000e008000000000001",
      "message": "We've let the team know. Someone will be with you shortly.",
      "state": "waiting_for_agent",
      "target": "live_chat"
    }
  ],
  "has_more": true,
  "next_cursor": "string"
}
```

## Errors [#errors]

| Status | Meaning |
| --- | --- |
| 400 | Bad Request ([error codes](/docs/api/errors)) |
| 401 | Unauthorized ([error codes](/docs/api/errors)) |
| 403 | Forbidden ([error codes](/docs/api/errors)) |
| 404 | Not Found ([error codes](/docs/api/errors)) |
| 422 | Unprocessable Content ([error codes](/docs/api/errors)) |
| 429 | Too Many Requests ([error codes](/docs/api/errors)) |