> ## Documentation Index > Fetch the complete documentation index at: https://app.miyon.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. # List conversations > Conversations of your account, newest first (by creation time, then id). Pages are offset based: new conversations can shift page boundaries while you paginate, so deduplicate by `id` and use fixed `from_date`/`to_date` bounds when traversing history. The response carries `has_more` instead of totals. List items never include transcripts; read a single conversation for its transcript. List and detail share one request quota per account (burst 30, then 0.5 requests per second). ## OpenAPI ````yaml /api-reference/openapi.yaml get /api/v1/conversations openapi: 3.1.0 info: title: Customer API version: 1.0.0-beta description: > **Beta.** This API is in beta. Contracts can still change while we complete it, including breaking changes; we announce changes in the release notes and keep them as rare as we can. Pin your integration to the field names and status codes documented here and treat unknown fields as optional. REST API to create and configure voice agents, add tools, test them with evals, read conversations, and place AI outbound calls. **Authentication.** Voice agents, settings, tools, evals and conversations use an API token created on the **Keys** page of your dashboard. Each operation lists the scope it needs under `x-required-scopes`; `:*` grants every action of a resource. Outbound calls use a separate outbound API token from the **Outbound Calls** page. Send either token as `Authorization: Bearer `. **Responses.** A single resource is returned as a flat JSON object; a collection is wrapped in a plural key (`voice_agents`, `tools`, `evals`, `conversations`) next to its paging fields. Deleting returns `204 No Content`. Everything is addressed by the voice agent's `id`; prompts and numbers are internal. **Errors.** Authentication failures return `{ "error", "message" }`. Request quotas return `429` with a `Retry-After` header and `{ "error", "message", "details" }`, where `error` is a stable machine-readable code. Every API call must finish within 30 seconds; longer requests return `503` with `mf-core:api-request-timeout`. Validation errors list the problems per field; the exact shape is shown on each operation. servers: - url: https://app.miyon.ai security: [] tags: - name: Voice Agents description: >- Create and manage voice agents. Configure them through the voice, prompt and knowledge-base settings endpoints. - name: Voice Agent Settings description: >- Read and change a voice agent's voice, prompt and knowledge-base settings. A voice agent has one prompt (its instructions, greeting and conversation settings). Read the schema of a settings group, then update one `key`/`value` pair per request. - name: Tools description: >- Create, configure, enable and execute agent tools. Tools are enabled per voice agent with `agent_id`. These endpoints accept scoped API tokens only; every error uses the `{ "error", "message", "details" }` envelope with a stable `mf-core:tool-*` code. - name: Outbound Calls description: >- Place AI calls and review their outcome. Authenticate with the outbound API token from the **Outbound Calls** page. - name: Conversations description: >- List and inspect the conversations of your account, including transcripts when your retention settings allow. - name: Evals description: >- Evals are automated test conversations that check how a voice agent responds. A scenario contains cases; each case contains the caller's turns and what the agent must say or do. Run a scenario to get pass/fail results. paths: /api/v1/conversations: get: tags: - Conversations summary: List conversations description: > Conversations of your account, newest first (by creation time, then id). Pages are offset based: new conversations can shift page boundaries while you paginate, so deduplicate by `id` and use fixed `from_date`/`to_date` bounds when traversing history. The response carries `has_more` instead of totals. List items never include transcripts; read a single conversation for its transcript. List and detail share one request quota per account (burst 30, then 0.5 requests per second). operationId: listConversations parameters: - name: page in: query schema: type: integer minimum: 1 default: 1 description: Page number, starting at 1. - name: per_page in: query schema: type: integer minimum: 1 maximum: 50 default: 20 description: Conversations per page (1-50). - name: from_date in: query description: >- Inclusive lower bound on the creation time. ISO 8601 date or timestamp; a value without offset is read in Europe/Berlin time. schema: type: string examples: - '2026-10-01' - '2026-10-01T08:00:00+02:00' - name: to_date in: query description: >- Inclusive upper bound on the creation time. ISO 8601 date or timestamp. Must not be earlier than `from_date`. schema: type: string - name: number in: query description: >- Filter by voice agent: its `id`, or its phone number. `all` disables the filter. schema: type: string - name: from_number in: query description: Substring match on the caller or sender number. schema: type: string - name: search_text in: query description: >- Substring match on the conversation name, caller number or dialed number. Transcript content is not searched. schema: type: string - name: channel in: query description: >- Restrict to one channel. Repeat the parameter as `channel[]=voice&channel[]=whatsapp` to select several. Unknown values are ignored. schema: type: string enum: - voice - livechat - whatsapp - email - name: result in: query description: > Restrict to conversations with a given call result (outcomes of voice tool calls). Accepts a result key such as `appointment_booked`, `transferred` or `sms_sent`; `group:` for a whole category (`forwarding`, `appointments`, `messaging`, `transfer`, `api_calls`); `api_call:` for one API tool; `any` for conversations with at least one result; `all` for no filter. schema: type: string examples: - appointment_booked - group:transfer - api_call:get_customer - any responses: '200': description: A page of conversations. content: application/json: schema: $ref: '#/components/schemas/ConversationListResponse' example: conversations: - id: 48213 conversation_id: outb_Ux7yQm2ZK9vLd0Rb1cAeTg call_id: outb_Ux7yQm2ZK9vLd0Rb1cAeTg channel: voice status: open agent_id: 42 agent_name: Booking agent started_at: '2026-10-15T09:12:03+02:00' ended_at: '2026-10-15T09:14:51+02:00' duration_seconds: 168 metadata: spent_tokens: 5120 message_count: 14 current_page: 1 per_page: 20 has_more: true '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '422': $ref: '#/components/responses/ConversationInvalidParameters' '429': $ref: '#/components/responses/RateLimited' '503': $ref: '#/components/responses/ServiceUnavailable' security: - scopedJwt: [] components: schemas: ConversationListResponse: type: object properties: conversations: type: array items: $ref: '#/components/schemas/Conversation' description: The page of conversations, newest first. current_page: type: integer description: Page returned. per_page: type: integer description: Page size applied. has_more: type: boolean description: True when another page exists. Totals are not provided. required: - conversations - current_page - per_page - has_more Conversation: type: object additionalProperties: false properties: id: type: integer description: ID of the conversation. conversation_id: type: string description: >- Stable public ID of the conversation. Accepted by `GET /api/v1/conversations/{id}`. call_id: type: - string - 'null' description: Telephony call identifier. Set for voice conversations only. channel: type: string enum: - voice - livechat - whatsapp - email - other description: Channel the conversation took place on. status: type: string const: open description: Always `open`; closed conversations are not returned. agent_id: type: - integer - 'null' description: >- The voice agent (its `id` from `GET /api/v1/voice_agents`) or messaging agent that handled the conversation. agent_name: type: - string - 'null' description: Name of the agent that handled the conversation. started_at: type: - string - 'null' format: date-time description: Call start for voice, otherwise when the conversation was created. ended_at: type: - string - 'null' format: date-time description: Call end for voice conversations; null for chats. duration_seconds: type: - integer - 'null' description: Call duration in seconds; null for chats. metadata: $ref: '#/components/schemas/ConversationMetadata' description: Usage figures of the conversation. transcript: type: array description: >- Detail responses only. Omitted when your retention settings do not allow access, the transcript has expired, or cleanup has already removed it. Hidden and technical messages are never included. items: $ref: '#/components/schemas/TranscriptMessage' required: - id - conversation_id - call_id - channel - status - agent_id - agent_name - started_at - ended_at - duration_seconds - metadata AuthError: type: object description: >- Returned when the API token is missing, invalid, expired or lacks the required scope. properties: error: type: string description: Short error category. examples: - Authentication failed - Forbidden message: type: string description: Human-readable explanation. Absent on some 403 responses. examples: - 'Missing required scope: voice_agents:write' required: - error ApiError: type: object description: >- Error format with a stable machine-readable `error` code, a human-readable `message` and request-specific `details`. properties: error: type: string description: >- Stable machine-readable error code, for example `mf-core:rate-limit-exceeded`. message: type: string description: Human-readable explanation. details: type: object additionalProperties: true description: >- Request-specific data, for example the offending parameter or the quota policy. required: - error - message - details ConversationMetadata: type: object description: >- Stored usage figures of the conversation. Only values that are known are included; nothing is computed on the fly. additionalProperties: false properties: spent_tokens: type: integer description: Total billable tokens attributed to the conversation. input_tokens: type: integer description: Tokens sent to the language model. output_tokens: type: integer description: Tokens generated by the language model. cached_input_tokens: type: integer description: Input tokens served from the model's cache. tool_call_count: type: integer description: Tool calls made during the conversation. message_count: type: integer description: Messages exchanged. estimated_cost_cents: type: integer description: Estimated cost in cents, when available. TranscriptMessage: type: object additionalProperties: false properties: role: type: string enum: - user - assistant - mixed - human_agent description: >- `user` is the caller or chat visitor, `assistant` the AI agent, `human_agent` a person who took over the chat, `mixed` a message with both user and agent content. content: type: string description: Text of the message. created_at: type: string format: date-time description: When the message was spoken or sent. required: - role - content - created_at responses: Unauthorized: description: Missing, expired or invalid bearer token. content: application/json: schema: $ref: '#/components/schemas/AuthError' example: error: Authentication failed message: Missing bearer token Forbidden: description: >- The token does not carry the scope this operation requires (see `x-required-scopes`). content: application/json: schema: $ref: '#/components/schemas/AuthError' example: error: Forbidden message: 'Missing required scope: voice_agents:write' ConversationInvalidParameters: description: A query parameter is invalid; `details.parameter` names it. content: application/json: schema: $ref: '#/components/schemas/ApiError' example: error: mf-core:invalid-conversation-parameters message: Invalid conversation parameters details: parameter: per_page RateLimited: description: >- Too many requests. Wait the number of seconds given in `Retry-After` before retrying. headers: Retry-After: description: Seconds to wait before retrying. schema: type: integer minimum: 1 content: application/json: schema: $ref: '#/components/schemas/ApiError' example: error: mf-core:rate-limit-exceeded message: Rate limit exceeded details: policy: api_write retry_after: 3 ServiceUnavailable: description: >- The request was not completed. Either it exceeded the 30-second request time limit that applies to every API call (narrow the request and retry), or rate limiting is temporarily unavailable. Retry shortly. content: application/json: schema: $ref: '#/components/schemas/ApiError' examples: timeout: value: error: mf-core:api-request-timeout message: The API request exceeded the 30-second time limit details: {} limiter: value: error: mf-core:rate-limiter-unavailable message: API rate limiting is temporarily unavailable details: policy: api_write securitySchemes: scopedJwt: type: http scheme: bearer bearerFormat: JWT description: >- Scoped API token. Required scopes are listed on each operation in x-required-scopes. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.