> ## Documentation Index
> Fetch the complete documentation index at: https://docs.poly.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# List all conversations

> Retrieves conversations for a given account and project. Supports three retrieval modes: transcript search, semantic search, and random sampling. When no retrieval mode is specified, the endpoint returns all conversations matching the given filters (default behavior). Only one retrieval mode may be specified per request.



## OpenAPI

````yaml GET /v3/{account_id}/{project_id}/conversations
openapi: 3.0.1
info:
  title: PolyAI Conversations API v3
  description: >-
    Schema for the PolyAI Conversations API v3.


    Compared to v1, v3:

    - Exposes additional turn-level fields (latency, translated_user_input,
    english_agent_response).

    - Normalizes empty text fields as empty strings rather than null.

    -
  license:
    name: MIT
  version: 3.0.0
servers:
  - url: https://api.us-1.platform.polyai.app
    description: US base url
  - url: https://api.uk-1.platform.polyai.app
    description: UK base url
  - url: https://api.euw-1.platform.polyai.app
    description: EUW base url
security:
  - ApiKeyAuth: []
paths:
  /v3/{account_id}/{project_id}/conversations:
    get:
      description: >-
        Retrieves conversations for a given account and project. Supports three
        retrieval modes: transcript search, semantic search, and random
        sampling. When no retrieval mode is specified, the endpoint returns all
        conversations matching the given filters (default behavior). Only one
        retrieval mode may be specified per request.
      parameters:
        - name: account_id
          in: path
          description: Account ID
          required: true
          schema:
            type: string
        - name: project_id
          in: path
          description: Project ID
          required: true
          schema:
            type: string
        - name: query_type
          in: query
          description: >-
            Search mode. Use `transcript` for full-text search over conversation
            transcripts, or `semantic` for vector similarity search. Requires
            `query` to be set. Mutually exclusive with `sample`.
          required: false
          schema:
            type: string
            enum:
              - transcript
              - semantic
        - name: sample
          in: query
          description: >-
            Sampling mode. Use `random` to return a random sample of
            conversations within the time range. No `query` required. Mutually
            exclusive with `query_type`.
          required: false
          schema:
            type: string
            enum:
              - random
        - name: query
          in: query
          description: >-
            The search text used for transcript or semantic search. Required
            when `query_type` is set.
          required: false
          schema:
            type: string
        - name: turn_type
          in: query
          description: >-
            Transcript search only. Filter by `user` or `agent` turns. Defaults
            to both.
          required: false
          schema:
            type: string
            enum:
              - user
              - agent
        - name: channel
          in: query
          description: >-
            One or more channels to filter by (e.g. voice, chat). Can be
            specified multiple times.
          required: false
          schema:
            type: array
            items:
              type: string
        - name: client_env
          in: query
          description: Client Environment - sandbox, pre-release or live
          schema:
            type: string
            enum:
              - sandbox
              - pre-release
              - live
            default: live
          example: sandbox
        - name: start_time
          in: query
          description: >-
            The start of the time range of the conversations to get, in ISO8601
            format
          example: '2021-07-01T14:15:00.000Z'
          required: false
          schema:
            type: string
            format: date-time
        - name: end_time
          in: query
          description: >-
            The end of the time range of the conversations to get, in ISO8601
            format
          example: '2021-07-01T16:35:00.000Z'
          required: false
          schema:
            type: string
            format: date-time
        - name: limit
          in: query
          description: >-
            Max number of conversations to return per API call. If the result
            set of your query is larger than this, it will be paginated.
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 1000
            default: 1000
        - name: offset
          in: query
          description: >-
            Offset within result set to fetch. Prefer `cursor` for paginating
            through large result sets — offset-based pagination becomes
            progressively slower at scale and may drift when conversations are
            written concurrently.
          required: false
          schema:
            type: integer
            minimum: 0
            default: 0
        - name: cursor
          in: query
          description: >-
            Opaque cursor for keyset pagination. Omit on the first request, then
            pass the `cursor` value returned by the previous response to fetch
            the next page. Cursors are URL-safe, encode the position within the
            result set, and remain stable as new conversations are written.
            Mutually preferable to `offset` for paginating through large result
            sets. Returns a 400 if the cursor value is malformed.
          required: false
          schema:
            type: string
        - name: variant_id
          in: query
          description: >-
            If it is set, we would return all conversations under this
            variant_id. Note that you may only specify either one of the
            variant_id or variant_name.
          required: false
          schema:
            type: string
        - name: variant_name
          in: query
          description: >-
            If it is set, we would return all conversations under this
            variant_name. Note that you may only specify either one of the
            variant_id or variant_name. Also, make sure to encode any spaces in
            the name with "%20"
          required: false
          schema:
            type: string
        - name: in_progress
          in: query
          description: >-
            If it is set to false, we only return finished conversations. If it
            is set to true, we only return conversations still in progress. By
            default, this parameter is None and we return all conversations.
          required: false
          schema:
            type: boolean
          example: false
        - name: include_latency
          in: query
          description: If true, include the latency info for each conversation.
          required: false
          schema:
            type: boolean
            default: false
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  conversations:
                    type: array
                    items:
                      $ref: '#/components/schemas/Conversation'
                  next_offset:
                    type: integer
                    description: >-
                      If present, the result is being paginated and requires
                      another API call to fetch the next portion (pass the
                      provided `next_offset` as the `offset` param for the next
                      API call). For new integrations, prefer the `cursor` field
                      for faster, drift-free pagination.
                  cursor:
                    type: string
                    nullable: true
                    description: >-
                      Opaque cursor pointing to the start of the next page. Pass
                      this value as the `cursor` query parameter on the next
                      request to fetch the following page. `null` when there are
                      no more pages.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  schemas:
    Conversation:
      type: object
      properties:
        id:
          type: string
          description: Unique ID for this conversation
          example: CAabcd1234567abcdef1250065d4fc7389
        account_id:
          type: string
          description: ID of the customer account this conversation is under.
        project_id:
          type: string
          description: ID of the project this conversation is under.
        variant_id:
          type: string
          description: ID of the variant this conversation is in.
        variant_name:
          type: string
          description: Name of the variant this conversation is in.
        environment:
          type: string
          description: >-
            Which deployment environment this conversation was handled in.
            Usually `live`, `sandbox`, or `pre-release`.
        started_at:
          type: string
          format: date-time
          description: The time when the conversation began, in ISO8601 format.
        channel:
          type: string
          description: >-
            What medium the conversation took place in. Usually one of `WEBCHAT`
            or `VOICE-SIP`.
        from_number:
          type: string
          description: Caller's phone number.
        to_number:
          type: string
          description: Phone number of the agent the caller was connected to.
        in_progress:
          type: boolean
          description: >-
            If true, the call is currently in progress, and therefore its
            properties may still change in the future.
        num_turns:
          type: integer
          description: >-
            Total number of turns in the conversation. This count should match
            the length of the turns array.
        total_duration:
          type: integer
          description: Duration of the entire call, in seconds.
        polyai_duration:
          type: integer
          description: >-
            Duration of the portion of the call handled by the PolyAI agent, in
            seconds.
        handoff:
          type: boolean
          description: Whether or not the PolyAI agent handed the call off.
        handoff_reason:
          type: string
          description: Brief reason why the agent handed the call off.
        handoff_destination:
          type: string
          description: If there are multiple handoff destinations, which one was used.
        num_silences:
          type: integer
          description: >-
            Number of turns in the conversation where the caller gave no
            discernible input.
        num_ood:
          type: integer
          description: >-
            Number of turns in the conversation where the caller gave some
            input, but it could not be understood by our agent.
        metrics:
          type: object
          description: >-
            Mapping name -> value of custom metrics logged by the agent. If a
            metric name was written more than once, the value will be a list of
            the values that were written. Timestamps, where present, use a
            consistent ISO8601 date-time format.
          additionalProperties:
            oneOf:
              - type: string
              - type: array
                items:
                  type: string
                minItems: 2
          example:
            CALL_DURATION: '30'
            CALL_TURN:
              - '2022-02-18T12:09:05.12677Z'
              - '2022-02-18T12:09:17.90602Z'
              - '2022-02-18T12:09:29.57732Z'
              - '2022-02-18T12:09:35.36996Z'
        state:
          type: object
          description: >-
            Mapping of keys -> values written to the dialogue state by the
            agent.
        turns:
          type: array
          description: >-
            Ordered list of turn objects in the conversation. May be empty if
            transcript access is disabled in the project's API configuration,
            even when num_turns is non-zero.
          items:
            $ref: '#/components/schemas/ConversationTurn'
      required:
        - id
        - account_id
        - project_id
        - environment
        - started_at
        - channel
        - in_progress
    ConversationTurn:
      type: object
      description: Info about a single turn.
      properties:
        user_input:
          type: string
          description: >-
            The transcription of what the user spoke or typed. May be an empty
            string when no input is present.
        user_input_dtmf:
          type: string
          description: >-
            DTMF digits captured for this turn (e.g. keypad input). May be an
            empty string when no DTMF was entered.
        user_input_datetime:
          type: string
          format: date-time
          description: >-
            The time when the agent received the user's input. For speech, this
            is when ASR finished transcribing.
        agent_response:
          type: string
          description: >-
            The transcription of the agent's response to the user. May be an
            empty string when no response was produced.
        agent_response_datetime:
          type: string
          format: date-time
          description: >-
            The time when the agent responded. For speech, this is when the
            agent started speaking.
        latency:
          type: number
          description: >-
            Agent latency for this turn (for example, time in seconds between
            receiving user input and starting the agent response).
        translated_user_input:
          type: string
          description: >-
            User input translated into the agent's working language (typically
            English) if translation is enabled. May be an empty string when not
            applicable.
        english_agent_response:
          type: string
          description: >-
            Agent response in English when translation is enabled. May be an
            empty string when not applicable.
        intents:
          type: array
          description: The list of intents that were found in this turn's input.
          items:
            type: string
        entities:
          type: array
          description: The list of entities that were found in this turn's input.
          items:
            type: object
            description: Mapping entity name -> value(s)
            additionalProperties:
              oneOf:
                - type: string
                - type: array
                  items:
                    type: string
        is_ood:
          type: boolean
          description: Whether the turn is classified as Out of Domain (OOD).
        is_silence:
          type: boolean
          description: Whether the turn is classified as a silence.
    Error:
      type: object
      properties:
        error_message:
          description: Reason for error.
          type: string
  responses:
    BadRequest:
      description: Bad Request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Unauthorized.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Not Found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    InternalError:
      description: Internal Server Error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: Contact your PolyAI representative.

````