List conversations

GET 
/ai/conversations

Retrieve a list of all AI conversations configured by the user. Supports PostgREST-style query parameters for filtering. Examples are included for the standard metadata fields, but you can filter on any field in the metadata JSON object. For example, to filter by a custom field metadata->custom_field, use metadata->custom_field=eq.value.

Query Parameters

id string

Filter by conversation ID (e.g. id=eq.123)

name string

Filter by conversation Name (e.g. name=like.Voice%)

created_at string

Filter by creation datetime (e.g., created_at=gte.2025-01-01)

last_message_at string

Filter by last message datetime (e.g., last_message_at=lte.2025-06-01)

metadata->assistant_id string

Filter by assistant ID (e.g., metadata->assistant_id=eq.assistant-123)

metadata->call_control_id string

Filter by call control ID (e.g., metadata->call_control_id=eq.v3:123)

metadata->telnyx_agent_target string

Filter by the phone number, SIP URI, or other identifier for the agent (e.g., metadata->telnyx_agent_target=eq.+13128675309)

metadata->telnyx_end_user_target string

Filter by the phone number, SIP URI, or other identifier for the end user (e.g., metadata->telnyx_end_user_target=eq.+13128675309)

metadata->telnyx_conversation_channel string

Filter by conversation channel (e.g., metadata->telnyx_conversation_channel=eq.phone_call)

limit integer

Possible values: >= 1

Limit the number of returned conversations (e.g., limit=10)

order string

Order the results by specific fields (e.g., order=created_at.desc or order=last_message_at.asc)

or string

Apply OR conditions using PostgREST syntax (e.g., or=(created_at.gte.2025-04-01,last_message_at.gte.2025-04-01))

200: Successful Response

application/json

• Schema
• Example (from schema)

Schema

data

object[]

required

Array [

id uuidrequired

name string

created_at date-timerequired

The datetime the conversation was created.

metadata

object

required

Metadata associated with the conversation. Telnyx provides several pieces of metadata, but customers can also add their own.

property name* string

Metadata associated with the conversation. Telnyx provides several pieces of metadata, but customers can also add their own.

last_message_at date-timerequired

The datetime of the latest message in the conversation.

]

{
  "data": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "",
      "created_at": "2025-04-15T13:07:28.764Z",
      "metadata": {
        "telnyx_conversation_channel": "phone_call",
        "telnyx_agent_target": "+13128675309",
        "telnyx_end_user_target": "+13128675309",
        "assistant_id": "assistant-123"
      },
      "last_message_at": "2025-04-15T13:07:28.764Z"
    }
  ]
}

422: Validation Error

application/json

• Schema
• Example (from schema)

Schema

detail

object[]

Array [

loc

object[]

required

Array [

anyOf

• MOD1
• MOD2

string

integer

]

msg Message (string)required

type Error Type (string)required

]

{
  "detail": [
    {
      "loc": [
        "string",
        0
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Request samples

• cURL

---

curl -L 'https://api.telnyx.com/v2/ai/conversations' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <TOKEN>'

Response samples

• 200
• 422

---

{
  "data": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "",
      "created_at": "2025-04-15T13:07:28.764Z",
      "metadata": {
        "telnyx_conversation_channel": "phone_call",
        "telnyx_agent_target": "+13128675309",
        "telnyx_end_user_target": "+13128675309",
        "assistant_id": "assistant-123"
      },
      "last_message_at": "2025-04-15T13:07:28.764Z"
    }
  ]
}

{
  "detail": [
    {
      "loc": [
        "string",
        0
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}