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

# List conversations

> Paginated list of conversations for the specified account and its subaccounts.



## OpenAPI

````yaml https://api.itellico.ai/v1/openapi.json get /v1/accounts/{account_id}/conversations
openapi: 3.1.0
info:
  title: itellicoAI API v1
  version: 1.0.0
  description: >-
    Public REST API for managing accounts, agents, telephony resources, and
    conversations.


    Authentication is via API key in the `X-API-Key` header.
  termsOfService: https://itellico.ai/legal/terms-and-conditions/
  contact:
    name: itellicoAI Support
    email: support@itellico.ai
  license:
    name: Proprietary
servers:
  - url: https://api.itellico.ai
    description: Production
security:
  - APIKeyAuth: []
tags:
  - name: Accounts
    description: >-
      Identify the current account context and fetch core account metadata to
      bootstrap API usage.
  - name: Subaccounts
    description: >-
      Create and manage child accounts under a parent to model tenant
      hierarchies and delegated access.
  - name: Agents
    description: >-
      Define and configure conversational agents (model, transcriber, voice,
      behavior) used in calls and automations.
  - name: Providers
    description: >-
      Discover available AI model, transcriber, and voice catalogs for the
      current account when configuring agents.
  - name: Phone Numbers
    description: >-
      Manage BYOC phone numbers bound to your account; route inbound calls to
      agents and enable outbound calling.
  - name: SIP Trunks
    description: >-
      Manage BYOC SIP trunk connectivity (origination/termination endpoints and
      allowed IPs) used by phone numbers.
  - name: Calls
    description: >-
      Create, list, inspect, and connect voice calls across phone and web
      channels.
  - name: Conversations
    description: List and inspect conversation activity across web and telephony channels.
  - name: Analytics
    description: Usage analytics and reporting endpoints for conversation activity.
paths:
  /v1/accounts/{account_id}/conversations:
    get:
      tags:
        - Conversations
      summary: List conversations
      description: >-
        Paginated list of conversations for the specified account and its
        subaccounts.
      operationId: listConversations
      parameters:
        - in: path
          name: account_id
          schema:
            title: Account Id
            type: string
          required: true
        - in: query
          name: conversation_id
          schema:
            anyOf:
              - format: uuid4
                type: string
              - type: 'null'
            description: Filter by conversation identifier.
            title: Conversation Id
          required: false
          description: Filter by conversation identifier.
        - in: query
          name: agent_id
          schema:
            anyOf:
              - format: uuid4
                type: string
              - type: 'null'
            description: Filter by agent UUID.
            title: Agent Id
          required: false
          description: Filter by agent UUID.
        - in: query
          name: type
          schema:
            anyOf:
              - $ref: '#/components/schemas/ConversationType'
              - type: 'null'
            description: Filter by conversation type (phone, web, or test).
          required: false
          description: Filter by conversation type (phone, web, or test).
        - in: query
          name: status
          schema:
            anyOf:
              - $ref: '#/components/schemas/ConversationStatus'
              - type: 'null'
            description: >-
              Filter by lifecycle status (in_progress, completed, failed,
              transferred).
          required: false
          description: >-
            Filter by lifecycle status (in_progress, completed, failed,
            transferred).
        - in: query
          name: direction
          schema:
            anyOf:
              - $ref: '#/components/schemas/ConversationDirection'
              - type: 'null'
            description: Filter by conversation direction (inbound or outbound).
          required: false
          description: Filter by conversation direction (inbound or outbound).
        - in: query
          name: created_after
          schema:
            anyOf:
              - format: date-time
                type: string
              - type: 'null'
            description: Return conversations created on/after this timestamp.
            title: Created After
          required: false
          description: Return conversations created on/after this timestamp.
        - in: query
          name: created_before
          schema:
            anyOf:
              - format: date-time
                type: string
              - type: 'null'
            description: Return conversations created before this timestamp.
            title: Created Before
          required: false
          description: Return conversations created before this timestamp.
        - in: query
          name: updated_after
          schema:
            anyOf:
              - format: date-time
                type: string
              - type: 'null'
            description: Return conversations updated on/after this timestamp.
            title: Updated After
          required: false
          description: Return conversations updated on/after this timestamp.
        - in: query
          name: updated_before
          schema:
            anyOf:
              - format: date-time
                type: string
              - type: 'null'
            description: Return conversations updated before this timestamp.
            title: Updated Before
          required: false
          description: Return conversations updated before this timestamp.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/NinjaPaginationResponseSchema_ConversationListItemSchema_
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
      security:
        - APIKeyAuth: []
components:
  schemas:
    ConversationType:
      description: High-level conversation types exposed via the v1 API.
      enum:
        - phone
        - web
        - test
        - unknown
      title: ConversationType
      type: string
    ConversationStatus:
      description: High-level lifecycle statuses reported by the conversations API.
      enum:
        - in_progress
        - completed
        - failed
        - transferred
      title: ConversationStatus
      type: string
    ConversationDirection:
      description: Directionality of a conversation.
      enum:
        - inbound
        - outbound
        - internal
      title: ConversationDirection
      type: string
    NinjaPaginationResponseSchema_ConversationListItemSchema_:
      properties:
        count:
          title: Count
          type: integer
        items:
          items:
            $ref: '#/components/schemas/ConversationListItemSchema'
          title: Items
          type: array
      required:
        - count
        - items
      title: NinjaPaginationResponseSchema[ConversationListItemSchema]
      type: object
    ErrorSchema:
      description: |-
        Standard error response payload for all API endpoints.

        Follows industry best practices (similar to Stripe, RetellAI):
        - code: Machine-readable error identifier for programmatic handling
        - message: Human-readable description for display
        - detail: Optional additional context for debugging
        - errors: Optional list of field-level validation errors
      examples:
        - code: not_found
          detail: Agent with UUID 123e4567-e89b-12d3-a456-426614174000 does not exist
          message: Resource not found
        - code: validation_error
          errors:
            - field: body.email
              message: Invalid email format
              type: value_error
            - field: body.name
              message: Field required
              type: missing
          message: Validation failed
      properties:
        code:
          description: Machine-readable error code (e.g., 'not_found', 'validation_error')
          title: Code
          type: string
        message:
          description: Human-readable error message
          title: Message
          type: string
        detail:
          anyOf:
            - type: string
            - type: 'null'
          description: Optional detailed context for debugging
          title: Detail
        errors:
          anyOf:
            - items:
                $ref: '#/components/schemas/FieldErrorSchema'
              type: array
            - type: 'null'
          description: Field-level validation errors (for 422 responses)
          title: Errors
      required:
        - code
        - message
      title: ErrorSchema
      type: object
    ConversationListItemSchema:
      description: Single conversation row returned by the list endpoint.
      properties:
        conversation_id:
          format: uuid4
          title: Conversation Id
          type: string
        type:
          $ref: '#/components/schemas/ConversationType'
          description: Conversation type classification (phone, web, or test).
        direction:
          anyOf:
            - $ref: '#/components/schemas/ConversationDirection'
            - type: 'null'
          description: Conversation direction when known.
        status:
          $ref: '#/components/schemas/ConversationStatus'
        agent_id:
          anyOf:
            - format: uuid4
              type: string
            - type: 'null'
          title: Agent Id
        agent_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Agent Name
        phone_number_id:
          anyOf:
            - format: uuid4
              type: string
            - type: 'null'
          title: Phone Number Id
        phone_number:
          anyOf:
            - type: string
            - type: 'null'
          description: Agent-side phone number when the type is phone.
          title: Phone Number
        contact_number:
          anyOf:
            - type: string
            - type: 'null'
          description: Contact-side phone number when the type is phone.
          title: Contact Number
        start_timestamp:
          format: date-time
          title: Start Timestamp
          type: string
        duration_seconds:
          anyOf:
            - minimum: 0
              type: integer
            - type: 'null'
          title: Duration Seconds
        messages:
          items:
            discriminator:
              mapping:
                agent:
                  $ref: '#/components/schemas/AgentMessageSchema'
                event:
                  $ref: '#/components/schemas/EventMessageSchema'
                system:
                  $ref: '#/components/schemas/SystemMessageSchema'
                tool:
                  $ref: '#/components/schemas/ToolMessageSchema'
                user:
                  $ref: '#/components/schemas/UserMessageSchema'
              propertyName: role
            oneOf:
              - $ref: '#/components/schemas/UserMessageSchema'
              - $ref: '#/components/schemas/AgentMessageSchema'
              - $ref: '#/components/schemas/SystemMessageSchema'
              - $ref: '#/components/schemas/ToolMessageSchema'
              - $ref: '#/components/schemas/EventMessageSchema'
          title: Messages
          type: array
        capture:
          anyOf:
            - $ref: '#/components/schemas/ConversationCaptureSchema'
            - type: 'null'
      required:
        - conversation_id
        - type
        - status
        - start_timestamp
      title: ConversationListItemSchema
      type: object
    FieldErrorSchema:
      description: Schema for individual field validation errors.
      properties:
        field:
          description: Field path (e.g., 'body.name', 'query.page')
          title: Field
          type: string
        message:
          description: Human-readable error message
          title: Message
          type: string
        type:
          description: Error type (e.g., 'value_error', 'type_error')
          title: Type
          type: string
      required:
        - field
        - message
        - type
      title: FieldErrorSchema
      type: object
    AgentMessageSchema:
      properties:
        role:
          const: agent
          default: agent
          title: Role
          type: string
        timestamp:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          description: UTC timestamp when the message was logged.
          title: Timestamp
        message:
          title: Message
          type: string
      required:
        - message
      title: AgentMessageSchema
      type: object
    EventMessageSchema:
      properties:
        role:
          const: event
          default: event
          title: Role
          type: string
        timestamp:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          description: UTC timestamp when the message was logged.
          title: Timestamp
        message:
          anyOf:
            - type: string
            - type: 'null'
          title: Message
      title: EventMessageSchema
      type: object
    SystemMessageSchema:
      properties:
        role:
          const: system
          default: system
          title: Role
          type: string
        timestamp:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          description: UTC timestamp when the message was logged.
          title: Timestamp
        message:
          title: Message
          type: string
      required:
        - message
      title: SystemMessageSchema
      type: object
    ToolMessageSchema:
      properties:
        role:
          const: tool
          default: tool
          title: Role
          type: string
        timestamp:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          description: UTC timestamp when the message was logged.
          title: Timestamp
        message:
          anyOf:
            - type: string
            - type: 'null'
          title: Message
        name:
          anyOf:
            - type: string
            - type: 'null'
          title: Name
        result:
          anyOf:
            - {}
            - type: 'null'
          title: Result
      title: ToolMessageSchema
      type: object
    UserMessageSchema:
      properties:
        role:
          const: user
          default: user
          title: Role
          type: string
        timestamp:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          description: UTC timestamp when the message was logged.
          title: Timestamp
        message:
          title: Message
          type: string
      required:
        - message
      title: UserMessageSchema
      type: object
    ConversationCaptureSchema:
      description: Capture artifacts associated with a conversation.
      properties:
        recording_url:
          anyOf:
            - type: string
            - type: 'null'
          description: URL or path to the conversation recording, when available.
          title: Recording Url
      title: ConversationCaptureSchema
      type: object
  securitySchemes:
    APIKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key

````