---
title: "Search Engagements"
method: GET
path: "/engagements/search/filtered"
tags: ["authenticated", "engagements"]
---

# Search Engagements

`GET /engagements/search/filtered`

## Request

- Base URL: `https://api-docs.upsmith.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api-docs.upsmith.com/engagements/search/filtered`
- Auth: one of:
  - API key in header `x-api-key`
  - HTTP bearer

## Query parameters

- `query` string, required
- `cursor` string, nullable
- `is_simulated` boolean, nullable
- `organization_ids` string[], nullable
- `match` 'identity' | 'hybrid'
- `filters` string, nullable
- `conversation_kind` 'customers' | 'ask_jenny', nullable

## Headers

- `organization-id` string, nullable
- `x-user-id` string, nullable
- `timezone` string
- `x-actor-email` string, nullable
- `x-request-source` string, nullable
- `x-operation-id` string, nullable
- `x-commit-message` string, nullable
- `x-confirmation-id` string, nullable
- `x-chat-id` string, nullable

## Response `200`

Successful Response

- ConversationSearchPage
  - `items` ConversationListItemPublic[], required
    - `engagement_id` string, required
    - `created_at` string, date-time, required
    - `status` 'active' | 'inactive' | 'sent' | 'paused' | 'aborted' | 'never_replied', required
    - `type` 'contact' | 'training' | 'ask_jenny' | 'slack', required
    - `is_ai_allowed_to_respond` boolean, required
    - `organization_id` string, required
    - `source` string, nullable
    - `manually_booked_at` string, date-time, nullable
    - `manually_booked_by_user_id` string, nullable
    - `hidden_at` string, date-time, nullable
    - `hidden_by_user_id` string, nullable
    - `has_agent_booking` boolean
    - `booking_status` 'booked' | 'requested' | 'none': The engagement's booking outcome. ``requested`` is an agent booking request the office has not turned into a booking — an outcome of its own, not a booking.
    - `agent_v2_id` string, nullable
    - `agent_v2_name` string, nullable
    - `agent_v2_voice_enabled` boolean, nullable
    - `agent_roster_key` string, nullable
    - `agent_variants` AgentVariantRefPublic[]
      - `id` string, required
      - `name` string, nullable
      - `is_production` boolean
      - `description` string, nullable
    - `objective_state` object, nullable
    - `override_agent_paused` boolean
    - `turn_number` integer, nullable
    - `metadata` object, nullable
    - `contact` ContactBasicPublic: Mirrors the ``ContactData`` GraphQL fragment (contact_id-keyed). COMMERCIAL name handling, the computed ``do_not_contact`` and ``href`` are produced by the router serializer, not read straight off the model.
      - `contact_id` string, required
      - `first_name` string, required
      - `last_name` string, nullable
      - `last_contacted` string, date-time, nullable
      - `href` string, nullable
      - `do_not_contact` boolean, required
    - `last_event` TimelineEventPublic
      - `id` string, required
      - `organization_id` string, required
      - `engagement_id` string, required
      - `origin` 'internal' | 'external', required
      - `role` 'user' | 'agent' | 'contact' | 'provider', required
      - `type` 'action' | 'interaction' | 'llm_response', required
      - `user_id` string, nullable
      - `created_at` string, date-time, required
      - `updated_at` string, date-time, required
      - `deleted_at` string, date-time, nullable
      - `user_initials` string, nullable
      - `interaction` TimelineEventInteractionPublic
        - `id` string, required
        - `channel_id` string, required
        - `contact_method_id` string, nullable
        - `image_id` string, nullable
        - `external_id` string, nullable
        - `twilio_message_status` string, nullable
        - `twilio_error_code` string, nullable
        - `telnyx_message_status` string, nullable
        - `telnyx_error_code` string, nullable
        - `metadata_json` object, nullable
        - `status` 'pending' | 'delivered' | 'received' | 'failed', required
        - `content` string, required
        - `translated_content` string, nullable
        - `deliver_after` string, date-time, nullable
        - `image` string, nullable
        - `image_content_type` string, nullable
        - `contact_method` ContactMethodPublic
          - `id` string, required
          - `type` 'phone' | 'email' | 'fax' | 'social', required
          - `social_platform` 'meta_messenger' | 'google_lsa' | 'instagram' | 'yelp' | 'thumbtack'
          - `phone_number` string, nullable
          - `email` string, nullable
          - `person_name` string, nullable
          - `person_role` string, nullable
      - `action` TimelineEventActionPublic
        - `id` string, required
        - `tool_module_id` string, required
        - `success` boolean, nullable
        - `type` 'booking' | 'booking_request'
        - `invocation_source` 'llm' | 'precall': Who invoked the tool that produced this action. ``LLM`` — the agent's model chose to call the tool mid-conversation. ``PRECALL`` — the system/operator ran the tool up front (before-turn hooks / pre-agent preload) and injected the result into the prompt; the model did not choose it. ``NULL`` means **legacy / unknown** — the row predates reliable tagging (ENG-4234) and is NOT necessarily LLM-invoked. Precalled tools were saved as actions before #4213 (2026-04-04), then not saved at all until ENG-4234, so historical rows are a mix we deliberately don't reconstruct. Readers must treat NULL as its own bucket, never fold it into ``LLM``. Only rows written after ENG-4234 shipped carry a trustworthy value.
        - `input` string, required
        - `output` string, required
        - `tool_module` ToolModulePublic
          - `id` string, required
          - `created_at` string, date-time, nullable
          - `updated_at` string, date-time, nullable
          - `deleted_at` string, date-time, nullable
          - `title` string, required
          - `description` string, required
          - `function` string, required
          - `disabled_reason` string, nullable
          - `read_only` boolean, required
      - `llm_response` EventLLMResponsePublic
        - `id` string, required
        - `phase` 'ModelRequest' | 'ModelResponse', required: Phase for persisted LLM transcript rows. Like other engagement ``StrEnum`` + ``sa.Enum(native_enum=False)`` columns, PostgreSQL stores the member **name** (``REQUEST`` / ``RESPONSE``) for ``llmphase``. The **value** strings are pydantic-ai message kinds (``ModelRequest`` / ``ModelResponse``) and are not written to this column.
        - `model` string, required
        - `content` union
          - object
          - unknown[]
            - unknown
          - string
        - `duration_ms` integer, nullable
    - `escalation_status` 'open' | 'claimed' | 'resolved' | 'under_control', required: Rollup of an engagement's escalations. Adds ``under_control`` (no escalations) on top of the per-escalation open/claimed/resolved states.
    - `waiting_since` string, date-time, nullable
    - `escalation_reason` string, nullable
    - `escalation_summary` string, nullable
    - `escalation_id` string, nullable
    - `ask_jenny_chat` AskJennyChatReference
      - `id` string, required
      - `title` string, nullable
      - `organization_id` string, required
  - `search_snippets` object
  - `search_match_kinds` object
  - `total` integer, nullable
  - `cursor` string, nullable
  - `search_mode` 'identity' | 'hybrid'
  - `semantic_available` boolean
  - `limit_reached` boolean

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/upsmith/apis/upsmith-api.md) - [All operations](https://skmtc.dev/upsmith/apis/upsmith-api/llms.txt) - [OpenAPI document](https://skmtc.dev/upsmith/apis/upsmith-api/revisions/86e2c2bd93af?raw)