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

# List conversations

Retrieves a paginated list of conversations for the authenticated organization. Supports filtering by status, agent assignment, tags, and full-text search. Results can be ordered by priority, date, or longest wait time. Pagination is cursor-based for efficient traversal of large datasets.


## OpenAPI

````yaml https://api.getfernand.com/openapi.json get /conversations
openapi: 3.0.3
info:
  title: Fernand API Documentation
  version: '3.0'
  description: This is the documentation for the [Fernand](https://getfernand.com) API.
  termsOfService: https://getfernand.com/terms
  contact:
    name: Fernand Support
    url: https://getfernand.com
    email: support@getfernand.com
  x-logo:
    url: https://app.getfernand.com/images/favicon/icon_128.png
servers:
  - url: https://api.getfernand.com
    description: ''
    x-last-modified: 1764750693905
security:
  - apiKeyHeader: []
externalDocs:
  description: You can access our documentation online by visiting https://api.fernand.help
  url: https://api.fernand.help
paths:
  /conversations:
    get:
      tags:
        - Conversations
      summary: List conversations
      description: >-
        Retrieves a paginated list of conversations for the authenticated
        organization. Supports filtering by status, agent assignment, tags, and
        full-text search. Results can be ordered by priority, date, or longest
        wait time. Pagination is cursor-based for efficient traversal of large
        datasets.
      operationId: listConversations
      parameters:
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 3
            maximum: 250
            default: 25
          description: Maximum number of conversations to return per page.
        - name: search
          in: query
          required: false
          schema:
            type: string
          description: >
            Search query string. Supports filtering by status, agent, tags, and
            keywords.

            Examples:
              - "status:opened" - Filter by status (opened, closed, spam, snoozed)
              - "assigned:jared@piedpiper.com" - Filter by agent email
              - "unassigned:true" - Show only unassigned conversations
              - "tag:urgent" - Filter by tag
              - "keyword search" - Full-text search in conversation content
        - name: cursor
          in: query
          required: false
          schema:
            type: string
          description: Pagination cursor from the previous response to fetch the next page.
        - name: order
          in: query
          required: false
          schema:
            type: string
            enum:
              - priority
              - oldest
              - newest
              - longest
            default: priority
          description: Sort order for conversations (priority, oldest, newest, or longest).
      responses:
        '200':
          description: List of conversations retrieved successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Conversation'
                  cursor:
                    type: string
                    nullable: true
                    description: >-
                      Cursor for fetching the next page, or null if no more
                      results.
        '400':
          description: Invalid parameters provided.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
components:
  schemas:
    Conversation:
      type: object
      properties:
        id:
          type: integer
          format: int64
          description: Unique identifier for the conversation
          example: 12345
        agent_id:
          type: integer
          format: int64
          nullable: true
          description: ID of the agent assigned to this conversation, or null if unassigned
          example: 42
        channel_id:
          type: integer
          format: int64
          nullable: true
          description: ID of the channel through which this conversation is conducted
          example: 1
        contact_id:
          type: integer
          format: int64
          description: ID of the primary contact who initiated the conversation
          example: 789
        subject:
          type: string
          maxLength: 250
          description: >-
            Subject line of the conversation, derived from the first message or
            manually set
          example: Question about billing
        status:
          type: string
          enum:
            - OPENED
            - CLOSED
            - SPAM
            - SNOOZED
          description: Current status of the conversation
          example: OPENED
        snooze_until:
          type: string
          format: date-time
          nullable: true
          description: >-
            ISO 8601 timestamp indicating when a snoozed conversation should
            reappear, or null if not snoozed
          example: '2026-01-22T09:00:00Z'
        last_update:
          type: string
          format: date-time
          description: ISO 8601 timestamp of the last incoming message in the conversation
          example: '2026-01-21T14:30:00Z'
        cursor:
          type: string
          nullable: true
          description: >-
            Pagination cursor for retrieving the next page of conversations in a
            list
          example: cur_1234567890
        tags:
          type: array
          items:
            type: integer
            format: int32
          description: Array of tag IDs associated with this conversation
          example:
            - 1
            - 5
            - 12
        recipients:
          type: array
          items:
            $ref: '#/components/schemas/Recipient'
          description: Array of recipients in the conversation (to, cc, bcc)
      required:
        - id
        - contact_id
        - subject
        - status
        - last_update
        - tags
        - recipients
      x-computed-hash: a4fe82348d6bfb626498c4e69d74844e7073707db3d01b4a3c48aa6f18ab85b1
      x-last-modified: 1769075324
    Recipient:
      type: object
      properties:
        id:
          type: integer
          format: int64
          description: Unique identifier for the recipient
          example: 12345
        contact_id:
          type: integer
          format: int64
          description: ID of the contact that is a recipient of this conversation
          example: 789
        kind:
          type: string
          enum:
            - to
            - cc
            - bcc
            - from
            - reply-to
          description: Type of recipient (to, cc, bcc, from, or reply-to)
          example: cc
        conversation_id:
          type: integer
          format: int64
          description: ID of the conversation this recipient belongs to
          example: 456
      required:
        - id
        - contact_id
        - kind
        - conversation_id
      x-computed-hash: cbb8eb868425947be377f9afbf0493c64e9e4591063f9430fa398020dbe2863c
      x-last-modified: 1769075324
  securitySchemes:
    apiKeyHeader:
      type: apiKey
      description: >-
        Authenticate your account by including your secret key in API requests.

        You can manage your API keys in the
        [Dashboard](https://app.getfernand.com/).


        Authentication to the API is performed by using the HTTP Header
        X-API-Key.
      name: X-API-Key
      in: header
      x-last-modified: 1764750344730

````