---
title: "Query user's unified context with AI"
method: POST
path: "/v1/users/{user_id}/query"
tags: ["Query (Metered)"]
---

# Query user's unified context with AI

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

## Request

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

Performs semantic retrieval across the user's connected messages, meetings, and calendar events, then returns an AI-generated answer.

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

**Use cases**:
- "What did Sarah say about the Q4 budget?"
- "Summarize my meeting with the engineering team last Tuesday"
- "Find all discussions about the product launch"

**Parameters**:
- `query`: The natural language question to answer (max 10,000 characters)
- `client_timezone`: User's timezone for date-aware queries
- `history`: Optional conversation history for follow-up questions (capped at 50 items / 64KB UTF-8; oldest are dropped past the cap with a `history_truncated_for_size_budget` warning, and a single message above the byte cap is rejected with `VALIDATION_OUT_OF_RANGE`)
- `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")
- `retrieval_mode`: Optional retrieval strategy — `"fast"` (lowest latency), `"auto"` (adaptive, default), or `"deep"` (full pipeline)
- `expand`: Optional comma-separated fields to include (e.g., "sources")
- `instructions`: Optional custom instructions for the AI (controls output format, filtering, conditional behavior — overrides default style, max 20,000 chars)
- `context`: Optional authoritative reference data the AI treats as ground truth (influences query rewriting but not used for vector search, max 20,000 chars)

**Response structure**:
- `answer`: AI-generated answer text
- `used_message_ids`: Message IDs (`msg_xxx`) used as source context
- `used_meeting_ids`: Meeting IDs (`mtg_xxx`) used as source context
- `used_event_ids`: Event IDs (`evt_xxx`) used as source context
- `used_note_ids`: Note IDs (`note_xxx`) used as source context
- `sources`: Optional human-readable snippets (only with `expand=sources`)
- If no relevant context is found, the request still succeeds with a plain-language `answer` and empty source ID arrays.

**Expand parameter**:
By default, `sources` (title/snippet pairs) are not included to reduce payload size.
Use `expand=sources` to include source snippets for display purposes.

## Path parameters

- `user_id` string, uuid, required

## Query parameters

- `expand` string

## Request body

- object
  - `query` string, required
  - `client_timezone` string
  - `history` object[]
    - `role` 'user' | 'assistant' | 'system', required
    - `content` 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)
  - `allow_bot_messages` boolean
  - `retrieval_mode` 'fast' | 'auto' | 'deep': Optional retrieval strategy. Defaults to 'auto' for /query requests.
  - `expand` string: Comma-separated list of fields to include (e.g., 'sources')
  - `instructions` string: Custom instructions for the AI. Controls output format, filtering, and conditional behavior. Takes priority over default style. Max 20,000 chars.
  - `context` string: Authoritative reference data for answer generation. The AI treats this as ground truth. Influences query rewriting but not used for vector search. Max 20,000 chars.

## Response `200`

Default Response

- object
  - `success` true, required
  - `data` object, required
    - `history` object[], required
      - `role` 'user' | 'assistant' | 'system', required
      - `content` string, required
    - `answer` string, required
    - `used_message_ids` string[], required
    - `used_meeting_ids` string[], required
    - `used_event_ids` string[], required
    - `used_note_ids` string[], required
    - `sources` object[]
      - `title` string, required
      - `snippet` string, required
    - `usage` object
      - `answer_generation` object, required: Synthesis chat-completion tokens only. See parent `usage` schema for full scope-coverage contract.
        - `model` string, required
        - `prompt_tokens` integer, required
        - `completion_tokens` integer, required
        - `total_tokens` integer, required
    - `no_context` true
    - `warnings` object[]
      - `code` 'records_truncated_for_token_budget' | 'retrieval_degraded' | 'thread_fetch_failed' | 'meeting_hydration_failed' | 'event_hydration_failed' | 'history_truncated_for_size_budget', required
      - `message` string, required
      - `dropped_record_count` integer
      - `degradations` string[]
      - `failed_count` integer
      - `dropped_item_count` integer
      - `dropped_content_bytes` integer
      - `max_history_items` integer
      - `max_history_content_bytes` 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)