---
title: "Video Searching Agent (SSE Stream)"
method: POST
path: "/queries/stream"
---

# Video Searching Agent (SSE Stream)

`POST /queries/stream`

Search and analyze videos across YouTube, TikTok, Instagram, and X/Twitter using an agentic Gemini loop. Returns results as Server-Sent Events (SSE).

## Request body

- object
  - `query` string, required — Natural-language search query
  - `platforms` string[] — Restrict to specific platforms. If omitted, all platforms are searched.
  - `max_results` integer — Maximum number of video results to return
  - `time_frame` 'past_24h' | 'past_week' | 'past_month' | 'past_year' — Recency filter for video results
  - `max_steps` integer — Maximum agent iteration steps
  - `enable_clarification` boolean — When true, the agent may return a clarification event instead of searching if the query is ambiguous

## Response `200`

SSE stream of agent events (started → progress → tool_call → tool_result → complete)

- object
  - `session_id` string — Unique session identifier
  - `query` string — Original user query
  - `answer` string — Natural-language answer summarizing findings
  - `video_references` object[] — Structured list of discovered videos
    - `video_id` string
    - `url` string
    - `title` string
    - `platform` string
    - `creator` string
    - `creator_url` string
    - `thumbnail_url` string
    - `relevance_note` string
    - `views` integer
    - `likes` integer
    - `comments` integer
    - `engagement_rate` number
    - `duration` string
    - `published_at` string
  - `platforms_searched` string[]
  - `total_videos_analyzed` integer
  - `total_creators_analyzed` integer
  - `confidence_score` number
  - `data_freshness` string
  - `steps_taken` integer
  - `tools_used` string[]
  - `execution_time_seconds` number
  - `usage_metrics` object
    - `token_usage` object
      - `input_tokens` integer
      - `output_tokens` integer
      - `total_tokens` integer
    - `gemini_calls` integer
    - `tool_invocations` object

## Other responses

- `400` — Invalid request

---

[API](https://skmtc.net/memories/apis/screenplay-extraction-api.md) · [All operations](https://skmtc.net/memories/apis/screenplay-extraction-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/memories/screenplay-extraction-api/versions/720c8c144ddc/schema)