> ## 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 conversations for an agent

> List recent conversations for an agent, with filters and limit/offset pagination. Served from api.{region}.poly.ai.



## OpenAPI

````yaml api-reference/conversations/v3/openapi.json GET /v1/agents/{agentId}/conversations
openapi: 3.1.0
info:
  title: PolyAI Builder MCP
  version: 1.0.0
  description: >-
    Every operation the Builder MCP (https://api.studio.poly.ai/builder-mcp and
    the other clusters' /builder-mcp listeners) exposes as a tool, drawn from
    the jupiter-api, sourcerer and supervisor-alerts public APIs and filtered to
    the routes published on the us-1-prod cluster. Each operation carries
    x-mcp-tool (the tool's name as MCP clients see it) and x-mcp-service (the
    backing service). Tool input schemas are the operation's parameters and
    request body; the gateway calls the operation on the caller's behalf with
    their API key or, over OAuth, a token exchanged for the signed-in user.
  x-mcp:
    name: builder
    listener_path: /builder-mcp
    services:
      - jupiter-api
      - sourcerer
      - supervisor-alerts
    tool_count: 131
servers:
  - url: https://api.us.poly.ai
    description: prod-us cluster
  - url: https://api.uk.poly.ai
    description: prod-uk cluster
  - url: https://api.eu.poly.ai
    description: prod-euw cluster
  - url: https://api.studio.poly.ai
    description: prod-plg cluster
security:
  - polyApiKey: []
  - oauth: []
paths:
  /v1/agents/{agentId}/conversations:
    parameters:
      - name: agentId
        in: path
        required: true
        schema:
          type: string
    get:
      tags:
        - Conversations
      summary: List conversations for a project
      description: |-
        List recent conversations for an agent with pagination.

        Returns conversation summaries. Fetch a single conversation by ID for
        full details.
      parameters:
        - name: limit
          in: query
          required: false
          schema:
            default: 50
            minimum: 1
            type: integer
          description: Max number of conversations to return
        - name: offset
          in: query
          required: false
          schema:
            default: 0
            minimum: 0
            type: integer
          description: Number of conversations to skip
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetConversationsResponse'
        '400':
          description: Validation error
        '401':
          description: Unauthorized – missing or invalid API key
        '403':
          description: Forbidden – insufficient permissions
components:
  schemas:
    GetConversationsResponse:
      description: |-
        A page of conversations matching the query, plus total count and
        limit/offset pagination.
      type: object
      properties:
        conversations:
          type: array
          items:
            $ref: '#/components/schemas/ConversationSummaryResponse'
        count:
          type: integer
        limit:
          type: integer
        offset:
          type: integer
      required:
        - conversations
        - count
        - limit
        - offset
    ConversationSummaryResponse:
      description: >-
        A conversation's top-level metadata, without its turn-by-turn
        transcript.
      type: object
      properties:
        conversationId:
          type: string
        accountId:
          type: string
        projectId:
          type: string
        createdAt:
          type:
            - string
            - 'null'
        startedAt:
          type:
            - string
            - 'null'
        finishedAt:
          type:
            - string
            - 'null'
        channel:
          type:
            - string
            - 'null'
        fromNumber:
          type:
            - string
            - 'null'
        toNumber:
          type:
            - string
            - 'null'
        language:
          type:
            - string
            - 'null'
        variantId:
          type:
            - string
            - 'null'
        clientEnv:
          type:
            - string
            - 'null'
        totalDuration:
          type:
            - integer
            - 'null'
        polyaiDuration:
          type:
            - integer
            - 'null'
        duration:
          type:
            - integer
            - 'null'
        inProgress:
          type:
            - boolean
            - 'null'
        handoff:
          type:
            - boolean
            - 'null'
        handoffDestination:
          type:
            - string
            - 'null'
        handoffReason:
          type:
            - string
            - 'null'
        direction:
          type:
            - string
            - 'null'
        tags:
          type:
            - array
            - 'null'
          items:
            type: string
        polyScore:
          type:
            - number
            - 'null'
        polyScoreV2:
          description: PolyScore on the 1-5 scale
          type:
            - number
            - 'null'
        customScores:
          description: >-
            Results for the project's AI Scores, sorted by name. An AI Score
            that was never run on this conversation (created after it ended,
            inactive at the time, or limited to other channels) has no entry.
            One that ran but was skipped or failed has an entry with that state
            and a null score
          type:
            - array
            - 'null'
          items:
            $ref: '#/components/schemas/CustomScoreResult'
        shortSummary:
          anyOf:
            - $ref: '#/components/schemas/ShortSummary'
            - type: 'null'
        deploymentId:
          type:
            - string
            - 'null'
        note:
          type:
            - string
            - 'null'
        audioUrl:
          type:
            - string
            - 'null'
      required:
        - conversationId
        - accountId
        - projectId
    CustomScoreResult:
      description: A conversation's result for one of the project's AI Scores.
      type: object
      properties:
        customScoreId:
          description: >-
            ID of the AI Score. Key results by this rather than by name, which
            can change
          type: string
        name:
          description: >-
            The AI Score's current name. Renaming a score changes it on every
            conversation, including ones scored before the rename
          type:
            - string
            - 'null'
        score:
          description: Score on the 1-5 scale. Null unless state is "processed"
          type:
            - number
            - 'null'
        state:
          description: >-
            Outcome of scoring: "processed", "skipped" (the conversation was too
            short, or matched the score's exclusion criteria), "failed" or
            "processing"
          type: string
      required:
        - customScoreId
        - state
    ShortSummary:
      description: Structured short summary with a heading and content.
      type: object
      properties:
        heading:
          description: Brief heading for the summary
          type: string
        content:
          description: Summary content
          type: string
      required:
        - heading
        - content
  securitySchemes:
    polyApiKey:
      type: apiKey
      in: header
      name: X-API-KEY
    oauth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        An MCP client's OAuth token for the listener, which Kong exchanges for a
        Platform API token about the user.

````