# Conversation Turns
Retrieve turns for a conversation.
Returns the ordered turns for a conversation with a specific user. On WhatsApp the user is identified by their phone number or Business-Scoped User ID (BSUID); on Instagram, by their Instagram-scoped ID or username. Each turn includes a stable turn ID and the available observed steps. Latency, status, and model output fields are included only when available. Malformed records and tool responses that cannot be matched to a tool call may be omitted.
## Base URL
| URL | Description |
|-----|-------------|
| https://api.facebook.com/{entity_id}/insights/conversations/turns | |
## Authorization
This API requires:
any of the following
- Capability: bizai_wa_enterprise_api_3p_access
- Capability: bizai_ig_enterprise_api_3p_access
- Permission: whatsapp_business_messaging
## APIs
| Method | Endpoint |
|--------|----------|
| GET | [/](#get) |
<jumplink id="get"></jumplink>
## GET /
Get conversation turns
Retrieve the ordered turns from the most recent conversation with the specified user. Each turn carries the model and tool-call steps the agent ran on its way to a response, so use this endpoint to see why the agent answered the way it did.
**Paging through results.** Turns are returned a page at a time. Set `limit` to choose the page size: it defaults to 25, and a value above 5000 is capped at 5000. Pass a cursor from the response in `after` to fetch the page that follows it, or in `before` to fetch the page ahead of it.
A short page does not mean you have reached the end. Turns can be filtered out after the limit is applied, so a request with `limit` set to 10 may return 9 turns and still have more available. Stop paging when the response no longer carries a next cursor, not when a page comes back short.
**Rate limit.** This endpoint allows 1,000 requests per hour for each app and `entity_id` pair. Once that is exhausted, further requests return `429` until the limit resets.
### Header Parameters
| Name | Type | Required | Description |
|------|------|----------|-------------|
| X-API-Version | "2.0.0" | | |
### Path Parameters
| Name | Type | Required | Description |
|------|------|----------|-------------|
| entity_id | string | ✓ | The WhatsApp Business Phone Number ID or Instagram account ID for the Meta Business Agent. |
### Query Parameters
| Name | Type | Required | Description |
|------|------|----------|-------------|
| user_phone_number | string | | Required when `entity_id` is a WhatsApp business phone number; not accepted for Instagram, which uses `user_id`. The consumer whose conversation turns should be retrieved. Accepts either a phone number in digits-only form (country code included, no leading `+`, spaces, or separators, e.g. `15551234567`), or a Business-Scoped User ID (BSUID) — a stable per-business identifier WhatsApp assigns to a consumer, formatted `<country>.<digits>` (e.g. `US.2788620304833812`). Any other phone-number formatting returns `Consumer not found`. Prefer the BSUID for any consumer who has ever adopted a WhatsApp username: their phone number may not be on file for your business, so a phone-number lookup can return `Consumer not found` even after the consumer deletes the username, while the BSUID resolves for any consumer who has messaged your business. BSUIDs arrive in webhook payloads as `messages[].from_user_id`, `message_echoes[].to_user_id`, `statuses[].recipient_user_id`, `contacts[].user_id`, and `state_sync[].contact.user_id`; see https://developers.facebook.com/documentation/business-messaging/whatsapp/business-scoped-user-ids for the full lifecycle. The `conversation_id` returned by the `agent_test` endpoint is also accepted. The server detects which type was provided based on the value format. |
| user_id | string | | Required when `entity_id` is an Instagram account; not accepted for WhatsApp, which uses `user_phone_number`. The consumer whose conversation turns should be retrieved: either the Instagram-scoped ID delivered to your webhook when the consumer messages your account, or the consumer's Instagram username, with or without the leading `@`. A value made up only of digits is read as a scoped ID, never as a username. The consumer must have an existing conversation with your account. |
| start_timestamp_ms | integer | | Return turns that started at or after this Unix epoch timestamp in milliseconds. The boundary is inclusive. |
| end_timestamp_ms | integer | | Return turns that started at or before this Unix epoch timestamp in milliseconds. The boundary is inclusive. |
| before | string | | If specified, a page of data immediately before this cursor will be returned. |
| after | string | | If specified, a page of data immediately after this cursor will be returned. |
| limit | integer | | This is the maximum number of objects that may be returned. A query may return fewer than the value of limit due to filtering. Do not depend on the number of results being fewer than the limit value to indicate that your query reached the end of the list of data, use the absence of next instead. For example, if you set limit to 10 and 9 results are returned, there may be more data available, but one item was removed due to privacy filtering. In all cases, the API returns the correct pagination links. |
### Responses
**200**
The turns for the conversation
**Content Type**: `application/json`
**Schema**: object
| Property | Type | Required | Description |
|----------|------|----------|-------------|
| data | array of [BizAIOmniChannelConversationTurn](#bizaiomnichannelconversationturn) | ✓ | This array represents the page of data returned. |
| paging | [Paging](#object-paging-2) | | Pagination metadata |
**400**
Bad request
**Content Type**: `application/json`
**Schema**: [StandardError](#standarderror)
**404**
Not found
**Content Type**: `application/json`
**Schema**: [StandardError](#standarderror)
**401**
Unauthorized
**Content Type**: `application/json`
**Schema**: [StandardError](#standarderror)
**403**
Forbidden
**Content Type**: `application/json`
**Schema**: [StandardError](#standarderror)
**429**
Too many requests
**Content Type**: `application/json`
**Schema**: [StandardError](#standarderror)
**500**
Server error
**Content Type**: `application/json`
**Schema**: [StandardError](#standarderror)
# Components
## Schemas
<jumplink id="bizaiomnichannelconversationturn"></jumplink>
### BizAIOmniChannelConversationTurn
| Property | Type | Required | Description |
|----------|------|----------|-------------|
| turn_id | string | ✓ | Stable identifier for the turn |
| message_id | string | | WhatsApp Cloud API message ID for the customer message that started the turn, reconstructed for the authorized consumer identity when available |
| agent_event | [Agent_event](#object-agent_event-3) | | The agent event you sent that started the turn, when the turn was started by an agent event rather than a customer message |
| e2e_latency_ms | integer | | Elapsed time, in milliseconds, from when the agent receives the customer message that starts the turn until the agent finishes producing its response, including model and tool-call processing time, if available |
| timestamp | integer | | Timestamp of the turn in milliseconds since epoch, if available |
| conversation_id | string | ✓ | App-scoped opaque identifier for the conversation containing this turn |
| steps | array of [Steps](#object-steps-4) | ✓ | Ordered steps observed during the turn |
<jumplink id="standarderror"></jumplink>
### StandardError
| Property | Type | Required | Description |
|----------|------|----------|-------------|
| detail | string | ✓ | |
| status | integer | | |
| title | string | ✓ | |
| type | string | | |
## Inline Object Definitions
<jumplink id="object-cursors-1"></jumplink>
### Cursors
Cursors to the next and previous pages
| Property | Type | Required | Description |
|----------|------|----------|-------------|
| before | string | | This is the cursor that points to the start of the page of data that has been returned. |
| after | string | | This is the cursor that points to the end of the page of data that has been returned. |
<jumplink id="object-paging-2"></jumplink>
### Paging
Pagination metadata
| Property | Type | Required | Description |
|----------|------|----------|-------------|
| cursors | [Cursors](#object-cursors-1) | ✓ | Cursors to the next and previous pages |
| previous | string | | The API that will return the previous page of data. If not included, this is the first page of data. |
| next | string | | The API that will return the next page of data. If not included, this is the last page of data. Due to how pagination works with visibility and privacy, it is possible that a page may be empty but contain a next paging link. Stop paging when the next link no longer appears. |
<jumplink id="object-agent_event-3"></jumplink>
### Agent_event
The agent event you sent that started the turn, when the turn was started by an agent event rather than a customer message
| Property | Type | Required | Description |
|----------|------|----------|-------------|
| type | string | ✓ | The event type you sent |
| description | string | | The event description you sent |
| payload | string | | The JSON payload you sent, as a string |
<jumplink id="object-steps-4"></jumplink>
### Steps
| Property | Type | Required | Description |
|----------|------|----------|-------------|
| type | One of "LLM_CALL", "TOOL_CALL" | ✓ | The type of step: LLM_CALL or TOOL_CALL |
| latency_ms | integer | | Latency for the step in milliseconds, if available |
| status | One of "SUCCESS", "ERROR", "TIMEOUT" | | The step status: SUCCESS, ERROR, or TIMEOUT |
| llm_output_preview | string | | A truncated preview of the model output, for LLM calls |
| tool_name | string | | The name of the tool used by this step, for tool calls |
| tool_input | string | | The input arguments passed to the tool, for tool calls |
| tool_output | string | | The output returned by the tool, for tool calls |
## Authentication
| Method | How to send it |
|--------|----------------|
| Authorization header | `Authorization: Bearer {access-token}` |
### Global Authentication Requirements
All endpoints require: `Authorization: Bearer {access-token}`