Skip to navigation

List

Returns conversations with optional filtering. Each item is the full conversation object returned by Get conversation, including transcripts, system_prompt and items.

Authentication

AuthorizationBearer

Bearer authentication header of the form Bearer <PHONIC_API_KEY>. Manage your API keys here.

Query parameters

projectstringOptionalDefaults to main
The name of the project to list conversations for.
external_idstringOptional
Filter by external ID to get a specific conversation.
duration_minintegerOptional>=0
Minimum duration in seconds.
duration_maxintegerOptional>=0
Maximum duration in seconds.
started_at_minstringOptional

Only return conversations that started at or after this time. Accepts a UTC date (2025-04-17) or a UTC date-time with milliseconds (2025-04-17T02:48:52.708Z). UTC offsets are not supported.

started_at_maxstringOptional

Only return conversations that started at or before this time. Accepts a UTC date (2025-04-17, meaning midnight at the start of that day) or a UTC date-time with milliseconds (2025-04-17T02:48:52.708Z). UTC offsets are not supported.

beforestringOptional

Cursor for backward pagination. Use a conversation ID from pagination.prev_cursor to fetch the previous page of conversations. Cannot be used with after.

afterstringOptional

Cursor for forward pagination. Use a conversation ID from pagination.next_cursor to fetch the next page of conversations. Cannot be used with before.

limitintegerOptional1-100Defaults to 20
Maximum number of conversations to return per page.
audio_containerenumOptionalDefaults to wav.gz

Format of the presigned audio_url in each conversation in the response.

Allowed values:

Response

Paginated list (conversations, pagination) when listing, or a single conversation when the external_id query parameter matches exactly one conversation.

ListConversationsResponseobject
OR
GetConversationByExternalIdResponseobject

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
404
Not Found Error
500
Internal Server Error