---
title: "Semantic search across user's context"
method: POST
path: "/v1/users/{user_id}/search"
tags: ["Search (Metered)"]
---

# Semantic search across user's context

`POST /v1/users/{user_id}/search`

## Request

- Base URL: `http://0.0.0.0:3000`
- URL: `http://0.0.0.0:3000/v1/users/{user_id}/search`
- Auth: none declared

Performs semantic search across the user's connected integrations and returns raw matches from messages, meetings, and calendar events.

**Billing**: This endpoint is metered. Each call consumes AI query credits.

**Use this when you need**:
- Raw communication data without AI summarization
- Full conversation threads plus matching meetings/events
- To build your own UI or processing on top of search results

**Response structure**:
- `key_messages`: Messages most relevant to the query
- `conversations`: Conversation threads containing the key messages
- `key_meetings`: Matched meetings (empty array when no meetings match)
- `key_events`: Matched calendar events (empty array when no events match)
- Every returned record includes `external_id` (partner-provided ID from ingest, or `null`)

**Parameters**:
- `query`: The search query (semantic, not keyword-based)
- `integration_ids`: Optional filter to specific integrations (opaque IDs like `int_xxx`)
- `conversation_ids`: Optional filter to specific conversations (opaque IDs, e.g., "conv_xxx")
- `after_date`: Optional date filter (YYYY-MM-DD)
- `before_date`: Optional date filter (YYYY-MM-DD)
- `sender_domains`: Optional filter by sender email domains (e.g., ["acme.com"])
- `entity_ids`: Optional filter by entity IDs (UUIDs)
- `retrieval_mode`: Optional retrieval strategy — `"fast"` (lowest latency, default), `"auto"` (adaptive), or `"deep"` (full pipeline)
- `expand`: Optional comma-separated fields to include (e.g., "body_text,summary,description")

**Expand parameter**:
By default, expandable detail fields are omitted to reduce payload size.
Use `expand=body_text` for message content, `expand=summary,short_summary,action_items,attendees,meeting_link` for meetings, and `expand=description,location,html_link,event_link,attendees` for calendar events.

## Path parameters

- `user_id` string, uuid, required

## Query parameters

- `expand` string

## Request body

- object
  - `query` string, required
  - `integration_ids` union[]: Filter to specific integrations by opaque ID (int_xxx). Numeric IDs are accepted for backward compatibility.
    - union
      - string
      - integer
  - `conversation_ids` string[]: Filter to specific conversations by opaque ID (conv_xxx)
  - `after_date` string, date: Filter results after this date (YYYY-MM-DD)
  - `before_date` string, date: Filter results before this date (YYYY-MM-DD)
  - `allow_bot_messages` boolean
  - `sender_domains` string[], nullable: Filter by sender email domains (e.g., ['acme.com'])
  - `entity_ids` string[], nullable: Filter by entity IDs (UUIDs)
  - `retrieval_mode` 'fast' | 'auto' | 'deep': Optional retrieval strategy. Defaults to 'fast' for /search requests.
  - `debug_retrieval_plan` boolean: When true, asks the retrieval backend to include extra planner diagnostics.
  - `max_results` integer: Maximum number of chunks to return. Chunks beyond rerank_top_k are appended in score order up to this cap.
  - `expand` string: Comma-separated list of fields to include (e.g., 'body_text,summary,action_items')

## Response `200`

Default Response

- object
  - `success` true, required
  - `data` object, required
    - `key_messages` object[], required
      - `message_id` number, required
      - `external_id` string, nullable, required: Partner-provided external_id from ingest, or null when absent
      - `thread_id` number, nullable
      - `conversation_id` number, nullable
      - `rank` number
    - `conversations` object, required: Map of conversation ID to conversation data with threads
    - `key_meetings` object[], required
      - `id` string, required: Opaque meeting ID (mtg_xxx)
      - `external_id` string, nullable, required: Partner-provided external_id from ingest, or null when absent
      - `title` string, required
      - `start_time` string, date-time, required
      - `end_time` string, date-time, required
      - `summary` string, nullable
      - `short_summary` string, nullable
      - `action_items` unknown[]
        - unknown
      - `attendees` unknown[]
        - unknown
      - `meeting_link` string, nullable
      - `has_transcript` boolean, required
      - `has_notes` boolean, required
      - `content_status` 'none' | 'notes_only' | 'transcript_only' | 'transcript_and_notes', required
      - `provider` string, required
      - `event_id` string, nullable
      - `meeting_code` string, nullable
      - `created_at` string, date-time, required
      - `updated_at` string, date-time, nullable
      - `rank` number
    - `key_events` object[], required
      - `id` string, required: Opaque event ID (evt_xxx)
      - `external_id` string, nullable, required: Partner-provided external_id from ingest, or null when absent
      - `calendar_id` string, required
      - `title` string, nullable, required
      - `description` string, nullable
      - `start_time` string, date-time, required
      - `end_time` string, date-time, required
      - `location` string, nullable
      - `status` string, nullable
      - `all_day` boolean, required
      - `created_at` string, date-time, required
      - `updated_at` string, date-time, nullable
      - `rank` number
    - `key_notes` object[], required
      - `note_id` number, required
      - `external_id` string, nullable, required: Partner-provided external_id from ingest, or null when absent
      - `rank` number
    - `rerank_provider` 'cohere' | 'tinybert' | 'none': Reranking model used in the retrieval pipeline
    - `degradations` string[]: Stable degradation codes emitted by the retrieval pipeline when results may be incomplete
    - `warnings` object[]: Structured warnings about degraded or partially hydrated results
      - `code` 'records_truncated_for_token_budget' | 'retrieval_degraded' | 'thread_fetch_failed' | 'meeting_hydration_failed' | 'event_hydration_failed' | 'note_hydration_failed' | 'identifiers_partial', required
      - `message` string, required
      - `dropped_record_count` integer
      - `degradations` string[]
      - `failed_count` integer
      - `missing_count` integer

## Other responses

- `400`: Default Response
- `500`: Default Response

---

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