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

# Search conversation items

> Search and filter items across all conversations. Supports keyword search across transcripts, summaries, and message content.

<Note>
  **Required scope:** `CONVERSATIONS_READ`
</Note>

This endpoint is paginated. Use `page` and `size` in the request body to control results. See [Pagination](/en/v2/api-reference/guides/pagination).

## Search behavior

The `search` field is a **keyword search**, not a natural language query. Extract keywords from the user's question before passing them.

| User asks                                             | `search` value         |
| ----------------------------------------------------- | ---------------------- |
| "Find calls where customers complained about billing" | `"billing complaint"`  |
| "What did we discuss about the refund policy?"        | `"refund policy"`      |
| "Show me conversations mentioning enterprise pricing" | `"enterprise pricing"` |

**How matching works:**

* Terms are **AND'd** — `"billing refund"` matches items containing **both** words
* **Prefix matching** is used — `"bill"` matches "billing", "billed", etc.
* Searches across: call transcripts, call summaries, and SMS message content
* Use `sort=RELEVANCE` to rank results by match quality instead of date

## Field notes

| Field           | Null when                                                 |
| --------------- | --------------------------------------------------------- |
| `summary`       | SMS items, or calls where AI summary is not yet available |
| `duration`      | SMS items (only applies to calls)                         |
| `result`        | SMS items (only applies to calls)                         |
| `recording_url` | Recording disabled, call not answered, or SMS items       |
| `transcript`    | Not requested via `extend=transcript`, or SMS items       |
| `content`       | Call items (only applies to SMS)                          |
| `status`        | Call items (only applies to SMS)                          |
| `tags`          | SMS items (tags only apply to calls)                      |

### Extend parameter

| Value        | Effect                                     |
| ------------ | ------------------------------------------ |
| `transcript` | Include full call transcripts on each item |

Passing an unsupported value returns a `400` error with code `UNSUPPORTED_EXTEND_VALUE`.


## OpenAPI

````yaml POST /v2/api/conversations/items/search
openapi: 3.0.3
info:
  title: Allo API
  description: >-
    Allo API provides programmatic access to your Allo account, allowing you to
    manage webhooks, retrieve calls and contacts, and send SMS messages.


    All requests to `/v1/api/**` endpoints automatically go through quota
    checking and scope validation.
  version: 1.0.0
  contact:
    name: Allo Support
servers:
  - url: https://api.withallo.com
    description: Production server
security: []
tags:
  - name: Summary Templates
    description: >-
      Manage call summary templates that control how AI-generated call summaries
      are structured for your team.
  - name: Webhooks
    description: >-
      Manage webhook endpoints to receive real-time notifications about events
      in your Allo account. Each endpoint subscribes to one or more event topics
      and is verified with a signing secret.
  - name: Calls
    description: >-
      Retrieve and search call records with filtering and pagination. Filter
      calls by your Allo phone number.
  - name: Contacts
    description: >-
      Search and retrieve contact information with sorting and pagination.
      Includes engagement level tracking.
  - name: SMS
    description: Send SMS messages to phone numbers using your Allo numbers.
  - name: Phone Numbers
    description: Retrieve information about your Allo phone numbers.
  - name: Analytics
    description: Pre-computed call metrics, team performance, and outbound dial funnel
  - name: CRM
    description: Manage people, companies, and deals in your CRM.
  - name: Notes
    description: >-
      Internal team notes on conversations and CRM people, with @mention
      support. Notes are never visible to the contact.
  - name: Threads
    description: >-
      Team discussion threads attached to a conversation item (call, SMS, or
      conversation note). One thread per item.
paths:
  /v2/api/conversations/items/search:
    post:
      tags:
        - Conversations
      summary: Search all conversations
      description: >-
        Search and filter items across all conversations. Supports keyword
        search across transcripts, summaries, and message content.
      operationId: searchAllConversations
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ItemSearchRequest'
            example:
              search: billing issues
              type: CALL
              sort: RELEVANCE
              date:
                from: '2026-01-01'
                to: '2026-04-21'
      responses:
        '200':
          description: Search results
          content:
            application/json:
              schema:
                allOf:
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/ConversationItem'
                  - $ref: '#/components/schemas/PaginatedResponse'
              example:
                data:
                  - id: cll-abc123
                    type: CALL
                    direction: INBOUND
                    allo_number: '+14155550100'
                    contact_number: '+14155551234'
                    contacts:
                      - id: cnt-abc123
                        name: Sarah Johnson
                    user:
                      id: usr-abc123
                      name: Alex Kim
                    date: '2026-04-21T14:30:00Z'
                    duration: 145
                    result: ANSWERED
                    recording_url: https://storage.withallo.com/recordings/cll-abc123.mp3
                    summary: >-
                      Customer called about a billing issue on their last
                      invoice.
                    tags:
                      - billing
                      - support
                pagination:
                  page: 1
                  size: 20
                  total_count: 1
                  total_pages: 1
                  has_more: false
        '400':
          $ref: '#/components/responses/ApiValidationError'
        '401':
          $ref: '#/components/responses/ApiUnauthorized'
        '429':
          $ref: '#/components/responses/ApiRateLimited'
      security:
        - ApiKeyAuth: []
components:
  schemas:
    ItemSearchRequest:
      type: object
      properties:
        allo_number:
          type: string
        contact_number:
          type: string
        user_id:
          type: string
        direction:
          type: string
          enum:
            - INBOUND
            - OUTBOUND
        type:
          type: string
          enum:
            - CALL
            - SMS
            - ALL
          default: ALL
        result:
          type: string
          enum:
            - ANSWERED
            - VOICEMAIL
            - TRANSFERRED
        tags:
          type: array
          items:
            type: string
        unread:
          type: boolean
        unresponded:
          type: boolean
        search:
          type: string
          description: >-
            Keyword search (not natural language). Extract keywords from the
            user's question. Terms are AND'd with prefix matching — 'billing
            refund' matches items containing both words, 'bill' matches
            'billing'. Searches across call transcripts, summaries, and SMS
            content.
        sort:
          type: string
          enum:
            - DATE_DESC
            - DATE_ASC
            - RELEVANCE
          default: DATE_DESC
        extend:
          type: string
        page:
          type: integer
          default: 1
        size:
          type: integer
          default: 20
          maximum: 100
        date:
          $ref: '#/components/schemas/AnalyticsDateRange'
          description: Date range to filter by
    ConversationItem:
      type: object
      properties:
        id:
          type: string
          example: cll-abc123
        type:
          type: string
          enum:
            - CALL
            - SMS
        direction:
          type: string
          enum:
            - INBOUND
            - OUTBOUND
        allo_number:
          type: string
          example: '+14155550100'
        contact_number:
          type: string
          example: '+14155551234'
        contacts:
          type: array
          items:
            $ref: '#/components/schemas/Contact'
        user:
          $ref: '#/components/schemas/UserRef'
        date:
          type: string
          format: date-time
        duration:
          type: integer
          nullable: true
        result:
          type: string
          nullable: true
          enum:
            - ANSWERED
            - VOICEMAIL
            - TRANSFERRED
        recording_url:
          type: string
          nullable: true
        summary:
          type: string
          nullable: true
        tags:
          type: array
          items:
            type: string
          nullable: true
        transcript:
          type: array
          nullable: true
          items:
            $ref: '#/components/schemas/TranscriptEntry'
        content:
          type: string
          nullable: true
        status:
          type: string
          nullable: true
          enum:
            - PENDING
            - SENT
            - DELIVERED
            - FAILED
        message_type:
          type: string
          nullable: true
          enum:
            - SMS
            - MMS
            - WHATSAPP
    PaginatedResponse:
      type: object
      properties:
        pagination:
          $ref: '#/components/schemas/Pagination'
    AnalyticsDateRange:
      type: object
      required:
        - from
        - to
      properties:
        from:
          type: string
          format: date
          description: Start date
          example: '2026-03-25'
        to:
          type: string
          format: date
          description: End date
          example: '2026-04-21'
    Contact:
      type: object
      properties:
        id:
          type: string
          example: cnt-abc123
        name:
          type: string
          example: Sarah Johnson
        company:
          type: object
          nullable: true
          properties:
            id:
              type: string
              example: com-xyz789
            name:
              type: string
              example: Acme Corp
        deals:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                example: dea-def456
              name:
                type: string
                example: Enterprise Plan
              status:
                type: string
                enum:
                  - OPEN
                  - WON
                  - LOST
    UserRef:
      type: object
      properties:
        id:
          type: string
          example: usr-abc123
        name:
          type: string
          example: John
        email:
          type: string
          example: john@acme.com
    TranscriptEntry:
      type: object
      properties:
        source:
          type: string
          enum:
            - USER
            - EXTERNAL
        time:
          type: string
          format: date-time
        text:
          type: string
    Pagination:
      type: object
      properties:
        page:
          type: integer
        size:
          type: integer
        total_count:
          type: integer
        total_pages:
          type: integer
        has_more:
          type: boolean
    ApiError:
      type: object
      properties:
        error:
          type: object
          properties:
            type:
              type: string
            code:
              type: string
            message:
              type: string
            retryable:
              type: boolean
            request_id:
              type: string
            retry_after_seconds:
              type: integer
              nullable: true
  responses:
    ApiValidationError:
      description: Invalid request parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    ApiUnauthorized:
      description: Invalid or missing API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    ApiRateLimited:
      description: Rate limit exceeded
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization

````