> ## Documentation Index
> Fetch the complete documentation index at: https://api-tools.memories.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Video Searching API
> Managed token-authenticated endpoint for agentic video search via SSE.
**Product**: Visual Agents
**Use case**: Managed endpoints powering Memories.ai's open-source video search and editing agents (queries, video clipping/editing, screenplay extraction)
**Host**: `https://mavi-backend.memories.ai/serve/api/v2`
**Auth**: `Authorization: sk-mavi-...` (no `Bearer` prefix)
The Video Searching API exposes the same agentic capabilities as the open-source Video Searching Agent through a managed, token-authenticated endpoint.
It searches YouTube, TikTok, Instagram, and X/Twitter, then returns structured findings via **Server-Sent Events (SSE)**.
This endpoint returns an **SSE stream**. In the playground above, click **Send** to fire the request. The response panel will show the raw SSE events as they arrive. For full streaming consumption, use the code examples below.
Real-time progress, tool calls, and final results streamed as typed SSE events.
YouTube, TikTok, Instagram, X/Twitter search & profile tools, Exa.ai neural search, and video analysis.
Billed per Gemini call and per third-party tool invocation. No idle cost.
### Code Examples
```bash cURL theme={null}
curl -N -X POST https://mavi-backend.memories.ai/serve/api/v2/queries/stream \
-H "Authorization: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"query": "Find trending AI coding tool videos on TikTok from the past week",
"platforms": ["tiktok"],
"max_results": 5,
"time_frame": "past_week"
}'
```
```javascript fetch theme={null}
const response = await fetch(
"https://mavi-backend.memories.ai/serve/api/v2/queries/stream",
{
method: "POST",
headers: {
Authorization: "YOUR_API_KEY",
"Content-Type": "application/json",
},
body: JSON.stringify({
query: "Find trending AI coding tool videos on TikTok from the past week",
platforms: ["tiktok"],
max_results: 5,
time_frame: "past_week",
}),
}
);
const reader = response.body.getReader();
const decoder = new TextDecoder();
while (true) {
const { done, value } = await reader.read();
if (done) break;
const text = decoder.decode(value);
// Each SSE chunk: "event: \ndata: \n\n"
console.log(text);
}
```
```python Python theme={null}
import httpx
with httpx.stream(
"POST",
"https://mavi-backend.memories.ai/serve/api/v2/queries/stream",
headers={"Authorization": "YOUR_API_KEY"},
json={
"query": "Find trending AI coding tool videos on TikTok from the past week",
"platforms": ["tiktok"],
"max_results": 5,
"time_frame": "past_week",
},
) as resp:
for line in resp.iter_lines():
print(line)
```
## SSE Event Types
The stream emits **named events** using the standard `event:` / `data:` SSE format. Each `data` payload is JSON.
### `started`
Emitted once when the agent session begins.
```json theme={null}
{
"session_id": "a1b2c3d4-...",
"query": "Find trending AI coding tool videos on TikTok from the past week"
}
```
### `progress`
Emitted at each agent step to indicate progress.
```json theme={null}
{
"step": 1,
"max_steps": 10,
"message": "Parsing query..."
}
```
### `clarification`
Emitted when `enable_clarification` is `true` and the query is ambiguous. The stream ends after this event.
```json theme={null}
{
"question": "Which platform would you like to focus on?",
"options": { "...": "..." }
}
```
### `tool_call`
Emitted when the agent invokes a tool.
```json theme={null}
{
"tool": "tiktok_search",
"arguments": {
"query": "AI coding tools",
"max_results": 5
}
}
```
### `tool_result`
Emitted after a tool finishes execution.
```json theme={null}
{
"tool": "tiktok_search",
"success": true,
"summary": "Found 5 videos"
}
```
### `error`
Emitted when a step or the entire run encounters a non-fatal error.
```json theme={null}
{
"message": "Tool tiktok_search failed: rate limited",
"step": 2
}
```
### `complete`
Final event containing the full structured response. The stream closes after this event.
```json theme={null}
{
"session_id": "a1b2c3d4-...",
"query": "Find trending AI coding tool videos on TikTok from the past week",
"answer": "Here are the top trending AI coding tool videos on TikTok from the past week...",
"video_references": [
{
"video_id": "7345678901234567890",
"url": "https://www.tiktok.com/@creator/video/7345678901234567890",
"title": "This AI writes code for you",
"platform": "tiktok",
"creator": "@creator",
"creator_url": "https://www.tiktok.com/@creator",
"thumbnail_url": "https://...",
"relevance_note": "High engagement, matches AI coding tools topic",
"views": 1500000,
"likes": 85000,
"comments": 3200,
"engagement_rate": 5.87,
"duration": "0:45",
"published_at": "2026-03-08T14:30:00Z"
}
],
"creator_analyses": null,
"comparisons": null,
"platforms_searched": ["tiktok"],
"total_videos_analyzed": 5,
"total_creators_analyzed": 4,
"confidence_score": 0.85,
"data_freshness": "past_week",
"steps_taken": 3,
"tools_used": ["tiktok_search", "video_search"],
"tool_execution_details": [
{
"tool": "tiktok_search",
"input": { "query": "AI coding tools", "max_results": 5 },
"result": "...",
"success": true
}
],
"execution_time_seconds": 8.4,
"usage_metrics": {
"token_usage": {
"input_tokens": 4200,
"output_tokens": 1800,
"total_tokens": 6000
},
"gemini_calls": 3,
"tool_invocations": { "tiktok_search": 1, "video_search": 1 }
},
"parsed_query": {
"original_query": "Find trending AI coding tool videos on TikTok from the past week",
"query_type": "discovery",
"platforms": ["tiktok"],
"topics": ["AI coding tools"],
"time_frame": "past_week",
"quantity": 5
}
}
```
## Response Fields
### Top-level
| Field | Type | Description |
| ------------------------- | ----------- | ---------------------------------------------------- |
| `session_id` | string | Unique session identifier |
| `query` | string | Original user query |
| `answer` | string | Natural-language answer summarizing findings |
| `video_references` | VideoRef\[] | Structured list of discovered videos |
| `creator_analyses` | object\[] | Creator-level insights (when query targets creators) |
| `comparisons` | object\[] | Side-by-side comparisons (when query is comparative) |
| `platforms_searched` | string\[] | Platforms that were actually queried |
| `total_videos_analyzed` | integer | Number of videos processed |
| `total_creators_analyzed` | integer | Number of unique creators found |
| `confidence_score` | number | 0–1 confidence in the answer quality |
| `data_freshness` | string | Time range of the returned data |
| `steps_taken` | integer | Number of agent loop iterations used |
| `tools_used` | string\[] | Distinct tool names invoked |
| `tool_execution_details` | object\[] | Per-tool input/output log |
| `execution_time_seconds` | number | Wall-clock time |
| `usage_metrics` | object | Token usage and tool invocation counts |
| `parsed_query` | object | Structured slots extracted from the query |
### VideoRef
| Field | Type | Description |
| ----------------- | ------- | ------------------------------------------------------------- |
| `video_id` | string | Platform-specific video identifier |
| `url` | string | Direct link to the video |
| `title` | string | Video title |
| `platform` | string | Source platform (`youtube`, `tiktok`, `instagram`, `twitter`) |
| `creator` | string | Creator handle |
| `creator_url` | string | Link to creator's profile |
| `thumbnail_url` | string | Thumbnail image URL |
| `relevance_note` | string | Why this video was selected |
| `views` | integer | View count |
| `likes` | integer | Like count |
| `comments` | integer | Comment count |
| `engagement_rate` | number | Engagement percentage |
| `duration` | string | Video duration |
| `published_at` | string | ISO 8601 publish timestamp |
## Available Tools
The agent autonomously selects from these tools during the agentic loop:
| Category | Tools | Description |
| --------- | ------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| YouTube | `youtube_search`, `youtube_channel_info` | Search videos and retrieve channel metadata |
| TikTok | `tiktok_search`, `tiktok_creator_info` | Search videos and retrieve creator profiles |
| Instagram | `instagram_search`, `instagram_creator_info` | Search reels/posts and retrieve creator profiles |
| X/Twitter | `twitter_search`, `twitter_profile` | Search tweets with video and retrieve user profiles |
| Exa.ai | `exa_search`, `exa_find_similar`, `exa_get_content`, `exa_research` | Neural web search, similar content discovery, page extraction, deep research |
| Unified | `video_search` | Cross-platform video search via Exa |
| Analysis | `social_media_metadata`, `social_media_transcript`, `social_media_mai_transcript`, `vlm_video_analysis` | Video metadata, transcript, visual transcript, and VLM analysis |
## Billing & Cost Breakdown
Each API call may trigger **multiple billable events** depending on which tools the agent selects. All charges are deducted automatically after successful execution — there is no upfront reservation per tool call.
### Gemini Model (Token-based)
The agent currently uses **Gemini 3.1 Pro** (`gemini-3.1-pro-preview`). Gemini is called at two stages, both billed by token count using the same `MODEL` billing type as the [Gemini VLM API](/visual-intelligence/gemini/gemini-vlm).
| Model | Input Price | Output Price |
| -------------------------- | --------------------------------------------- | ----------------------------------------------- |
| **gemini-3.1-pro-preview** | \$2/1M tokens (≤200K context), \$4/1M (>200K) | \$12/1M tokens (≤200K context), \$18/1M (>200K) |
| Trigger Point | When | Billing |
| -------------------------- | ------------------------------------------------------------------------------- | -------------------------------------------------- |
| **Query Classification** | Once per request — parses the query into structured slots | `MODEL` — input + output tokens at the price above |
| **Agentic Loop Iteration** | Each loop step where Gemini decides the next tool or generates the final answer | `MODEL` — input + output tokens at the price above |
A typical request with 3 agent steps produces **4 Gemini billing events** (1 classification + 3 loop iterations). The exact token counts are returned in `usage_metrics.token_usage`.
### Social Platform Search Tools
These tools call third-party scraping APIs (Apify or RapidAPI). The agent picks the available channel automatically.
| Tool | Billing Type | Price per call | Triggered When |
| ------------------ | --------------------------------------------------- | -------------- | ------------------------------------ |
| `tiktok_search` | `TIKTOK_APIFY_SEARCH` / `TIKTOK_RAPID_SEARCH` | \$0.02 | Agent searches TikTok videos |
| `instagram_search` | `INSTAGRAM_APIFY_SEARCH` / `INSTAGRAM_RAPID_SEARCH` | \$0.02 | Agent searches Instagram reels/posts |
| `twitter_search` | `TWITTER_APIFY_SEARCH` / `TWITTER_RAPID_SEARCH` | \$0.02 | Agent searches X/Twitter posts |
### Creator / Profile Tools
| Tool | Billing Type | Price per call | Triggered When |
| ------------------------ | ------------------------- | -------------- | ------------------------------------------ |
| `tiktok_creator_info` | `TIKTOK_RAPID_CREATOR` | \$0.02 | Agent fetches a TikTok creator profile |
| `instagram_creator_info` | `INSTAGRAM_RAPID_CREATOR` | \$0.02 | Agent fetches an Instagram creator profile |
| `twitter_profile` | `TWITTER_RAPID_PROFILE` | \$0.02 | Agent fetches an X/Twitter user profile |
### Exa.ai Tools
| Tool | Billing Type | Price | Unit | Triggered When |
| ------------------ | ------------------ | ------- | ---------------------- | ------------------------------------------- |
| `exa_search` | `EXA_SEARCH` | \$0.007 | per call | Neural web search |
| `video_search` | `EXA_VIDEO_SEARCH` | \$0.007 | per call | Cross-platform video search via Exa |
| `exa_research` | `EXA_RESEARCH` | \$0.007 | per call | Deep topic research with content extraction |
| `exa_find_similar` | `EXA_SIMILAR` | \$0.007 | per call | Find pages similar to a given URL |
| `exa_get_content` | `EXA_CONTENT` | \$0.001 | **per URL** (up to 10) | Extract text content from URLs |
`exa_get_content` is the only tool billed **per item** rather than per call. If the agent extracts content from 5 URLs in a single invocation, 5 × \$0.001 = \$0.005 is charged.
### YouTube Tools — Free
| Tool | Billing | Note |
| ---------------------- | ------------- | -------------------------------- |
| `youtube_search` | **No charge** | Uses free YouTube Data API quota |
| `youtube_channel_info` | **No charge** | Uses free YouTube Data API quota |
### Video Analysis Tools — Billed by Underlying Service
These tools call existing Memories.ai internal services that have their own billing. No additional agent-level charge is applied. See the corresponding API docs for pricing:
| Tool | Underlying Billing | Triggered When |
| ----------------------------- | ---------------------------------------------------------------- | -------------------------------------------------------- |
| `social_media_metadata` | Standard metadata API pricing | Agent fetches video metadata by URL |
| `social_media_transcript` | Standard transcript API pricing | Agent fetches video transcript |
| `social_media_mai_transcript` | Standard MAI transcript API pricing | Agent fetches visual (MAI) transcript |
| `vlm_video_analysis` | [Gemini VLM API pricing](/visual-intelligence/gemini/gemini-vlm) | Agent performs visual-language model analysis on a video |
### Cost Example
A typical discovery query like *"Find trending AI videos on TikTok this week"* may incur:
| Item | Count | Unit Price | Subtotal |
| ---------------------- | ---------------------------------------- | ---------------------- | ------------ |
| Gemini classification | 1 call (\~500 in / 200 out tokens) | \$2/1M in, \$12/1M out | \~\$0.0034 |
| Gemini loop iterations | 3 calls (\~3000 in / 600 out tokens avg) | \$2/1M in, \$12/1M out | \~\$0.0396 |
| `tiktok_search` | 1 | \$0.02 | \$0.02 |
| `video_search` | 1 | \$0.007 | \$0.007 |
| **Estimated total** | | | **\~\$0.07** |
You can inspect the exact tools invoked and their counts in the `complete` event's `usage_metrics.tool_invocations` and `tools_used` fields.
## Error Handling
If the request body is invalid, the endpoint returns a standard JSON error (not SSE):
```json theme={null}
{
"code": 400,
"message": "query is required"
}
```
For errors during the agentic loop, an `error` SSE event is emitted and the stream may still complete with partial results.
## Rate Limits
This endpoint uses the **Lite** rate-limit tier. Check your plan for specific limits.
The streaming endpoint keeps the connection open for up to **5 minutes**. A keep-alive ping comment is sent every 15 seconds to prevent proxy timeouts.
## OpenAPI
````yaml POST /queries/stream
openapi: 3.1.0
info:
title: Visual Agents API
description: REST APIs for Video Searching Agent
version: v1.0.0
servers:
- url: https://mavi-backend.memories.ai/serve/api/v2
security:
- ApiKeyAuth: []
paths:
/queries/stream:
post:
summary: Video Searching Agent (SSE Stream)
description: >-
Search and analyze videos across YouTube, TikTok, Instagram, and
X/Twitter using an agentic Gemini loop. Returns results as Server-Sent
Events (SSE).
operationId: video_searching_agent_stream
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- query
properties:
query:
type: string
description: Natural-language search query
example: >-
Find trending AI coding tool videos on TikTok from the past
week
platforms:
type: array
items:
type: string
enum:
- youtube
- tiktok
- instagram
- twitter
description: >-
Restrict to specific platforms. If omitted, all platforms
are searched.
max_results:
type: integer
default: 10
description: Maximum number of video results to return
time_frame:
type: string
enum:
- past_24h
- past_week
- past_month
- past_year
description: Recency filter for video results
max_steps:
type: integer
default: 10
description: Maximum agent iteration steps
enable_clarification:
type: boolean
default: false
description: >-
When true, the agent may return a clarification event
instead of searching if the query is ambiguous
responses:
'200':
description: >-
SSE stream of agent events (started → progress → tool_call →
tool_result → complete)
content:
application/json:
schema:
type: object
properties:
session_id:
type: string
description: Unique session identifier
query:
type: string
description: Original user query
answer:
type: string
description: Natural-language answer summarizing findings
video_references:
type: array
description: Structured list of discovered videos
items:
type: object
properties:
video_id:
type: string
url:
type: string
title:
type: string
platform:
type: string
creator:
type: string
creator_url:
type: string
thumbnail_url:
type: string
relevance_note:
type: string
views:
type: integer
likes:
type: integer
comments:
type: integer
engagement_rate:
type: number
duration:
type: string
published_at:
type: string
platforms_searched:
type: array
items:
type: string
total_videos_analyzed:
type: integer
total_creators_analyzed:
type: integer
confidence_score:
type: number
data_freshness:
type: string
steps_taken:
type: integer
tools_used:
type: array
items:
type: string
execution_time_seconds:
type: number
usage_metrics:
type: object
properties:
token_usage:
type: object
properties:
input_tokens:
type: integer
output_tokens:
type: integer
total_tokens:
type: integer
gemini_calls:
type: integer
tool_invocations:
type: object
'400':
description: Invalid request
content:
application/json:
schema:
type: object
properties:
code:
type: integer
message:
type: string
components:
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: Authorization
````