Agentic Search Stream

Stream real-time agentic search progress via Server-Sent Events

POST /v1/collections/{readable_id}/agentic-search/stream

Agentic Search Stream

cURL

curl --request POST \
  --url https://api.example.com/v1/collections/{readable_id}/agentic-search/stream \
  --header 'Content-Type: application/json' \
  --data '
{
  "query": "<string>",
  "mode": "<string>",
  "filter": [
    {}
  ],
  "limit": 123
}
'

200

{
  "planning": {},
  "search": {},
  "evaluation": {},
  "done": {},
  "error": {}
}

Overview

Stream agentic search progress in real-time using Server-Sent Events (SSE). This endpoint provides live updates as the agent plans, searches, and evaluates results.

Event Stream:

• Planning reasoning and strategy
• Search execution with statistics
• Evaluator assessments of result quality
• Final results and answer

Benefits:

• Build interactive search UIs with live feedback
• Monitor agent decision-making process
• Track search progress for long-running queries
• Debug search strategies

Path Parameters

readable_id · string · required

The unique readable identifier of the collection to search

Example: “customer-docs-x7k9m”

Request Body

query · string · required

The natural language search query

mode · string · default: "thinking"

Search execution mode: thinking or fast

filter · array · default: []

Filter groups applied to search results

limit · integer

Maximum number of results to return

Response

Returns a Server-Sent Events (SSE) stream with text/event-stream content type.

Event Types

planning · event

Agent’s reasoning and search strategy

Show payload example

{
  "type": "planning",
  "reasoning": "The query asks about authentication best practices. I'll search for security documentation and API key management guides.",
  "strategy": "hybrid_search_with_filters"
}

search · event

Search execution with result counts

Show payload example

{
  "type": "search",
  "query": "authentication best practices",
  "results_found": 45,
  "filters_applied": true
}

evaluation · event

Evaluator’s assessment of result quality

Show payload example

{
  "type": "evaluation",
  "quality_score": 0.92,
  "needs_refinement": false,
  "reasoning": "Results contain comprehensive authentication documentation"
}

done · event

Final results and answer

Show payload example

{
  "type": "done",
  "results": [...],
  "answer": {
    "text": "Based on the documentation...",
    "citations": [{"entity_id": "abc123"}]
  }
}

error · event

Error event if something goes wrong

Show payload example

{
  "type": "error",
  "message": "Search service unavailable"
}

Example Request

cURL

curl -N -X POST https://api.airweave.ai/v1/collections/customer-docs-x7k9m/agentic-search/stream \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "query": "What are the authentication best practices?",
    "mode": "thinking"
  }'

Example Event Stream

data: {"type": "planning", "reasoning": "Query asks about authentication best practices", "strategy": "hybrid_search"}

data: {"type": "search", "query": "authentication best practices", "results_found": 45}

data: {"type": "evaluation", "quality_score": 0.92, "needs_refinement": false}

data: {"type": "done", "results": [...], "answer": {"text": "Based on the documentation...", "citations": [...]}}

Connection Management

• Auto-close: Connection closes when search completes or encounters an error
• Error handling: Errors are sent as events before closing
• Buffering disabled: X-Accel-Buffering: no header disables proxy buffering

Headers

The response includes:

• Content-Type: text/event-stream
• Cache-Control: no-cache, no-transform
• Connection: keep-alive
• X-Accel-Buffering: no
• Access-Control-Allow-Origin: *

Error Responses

403 Forbidden

AGENTIC_SEARCH feature not enabled for this organization

404 Not Found

Collection with the specified readable_id does not exist

422 Validation Error

Invalid query (empty or invalid parameters)

429 Too Many Requests

Query limit exceeded for your organization