Video Searching Agent (SSE Stream)
curl --request POST \
--url https://mavi-backend.memories.ai/serve/api/v2/queries/stream \
--header 'Authorization: <api-key>' \
--header 'Content-Type: application/json' \
--data '
{
"query": "Find trending AI coding tool videos on TikTok from the past week",
"platforms": [],
"max_results": 10,
"max_steps": 10,
"enable_clarification": false
}
'import requests
url = "https://mavi-backend.memories.ai/serve/api/v2/queries/stream"
payload = {
"query": "Find trending AI coding tool videos on TikTok from the past week",
"platforms": [],
"max_results": 10,
"max_steps": 10,
"enable_clarification": False
}
headers = {
"Authorization": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
query: 'Find trending AI coding tool videos on TikTok from the past week',
platforms: [],
max_results: 10,
max_steps: 10,
enable_clarification: false
})
};
fetch('https://mavi-backend.memories.ai/serve/api/v2/queries/stream', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://mavi-backend.memories.ai/serve/api/v2/queries/stream",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'query' => 'Find trending AI coding tool videos on TikTok from the past week',
'platforms' => [
],
'max_results' => 10,
'max_steps' => 10,
'enable_clarification' => false
]),
CURLOPT_HTTPHEADER => [
"Authorization: <api-key>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://mavi-backend.memories.ai/serve/api/v2/queries/stream"
payload := strings.NewReader("{\n \"query\": \"Find trending AI coding tool videos on TikTok from the past week\",\n \"platforms\": [],\n \"max_results\": 10,\n \"max_steps\": 10,\n \"enable_clarification\": false\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://mavi-backend.memories.ai/serve/api/v2/queries/stream")
.header("Authorization", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"query\": \"Find trending AI coding tool videos on TikTok from the past week\",\n \"platforms\": [],\n \"max_results\": 10,\n \"max_steps\": 10,\n \"enable_clarification\": false\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://mavi-backend.memories.ai/serve/api/v2/queries/stream")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"query\": \"Find trending AI coding tool videos on TikTok from the past week\",\n \"platforms\": [],\n \"max_results\": 10,\n \"max_steps\": 10,\n \"enable_clarification\": false\n}"
response = http.request(request)
puts response.read_body{
"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
}
}
Video Searching Agent
Video Searching API
Managed token-authenticated endpoint for agentic video search via SSE.
POST
/
queries
/
stream
Video Searching Agent (SSE Stream)
curl --request POST \
--url https://mavi-backend.memories.ai/serve/api/v2/queries/stream \
--header 'Authorization: <api-key>' \
--header 'Content-Type: application/json' \
--data '
{
"query": "Find trending AI coding tool videos on TikTok from the past week",
"platforms": [],
"max_results": 10,
"max_steps": 10,
"enable_clarification": false
}
'import requests
url = "https://mavi-backend.memories.ai/serve/api/v2/queries/stream"
payload = {
"query": "Find trending AI coding tool videos on TikTok from the past week",
"platforms": [],
"max_results": 10,
"max_steps": 10,
"enable_clarification": False
}
headers = {
"Authorization": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
query: 'Find trending AI coding tool videos on TikTok from the past week',
platforms: [],
max_results: 10,
max_steps: 10,
enable_clarification: false
})
};
fetch('https://mavi-backend.memories.ai/serve/api/v2/queries/stream', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://mavi-backend.memories.ai/serve/api/v2/queries/stream",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'query' => 'Find trending AI coding tool videos on TikTok from the past week',
'platforms' => [
],
'max_results' => 10,
'max_steps' => 10,
'enable_clarification' => false
]),
CURLOPT_HTTPHEADER => [
"Authorization: <api-key>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://mavi-backend.memories.ai/serve/api/v2/queries/stream"
payload := strings.NewReader("{\n \"query\": \"Find trending AI coding tool videos on TikTok from the past week\",\n \"platforms\": [],\n \"max_results\": 10,\n \"max_steps\": 10,\n \"enable_clarification\": false\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://mavi-backend.memories.ai/serve/api/v2/queries/stream")
.header("Authorization", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"query\": \"Find trending AI coding tool videos on TikTok from the past week\",\n \"platforms\": [],\n \"max_results\": 10,\n \"max_steps\": 10,\n \"enable_clarification\": false\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://mavi-backend.memories.ai/serve/api/v2/queries/stream")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"query\": \"Find trending AI coding tool videos on TikTok from the past week\",\n \"platforms\": [],\n \"max_results\": 10,\n \"max_steps\": 10,\n \"enable_clarification\": false\n}"
response = http.request(request)
puts response.read_body{
"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
}
}
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)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.
SSE Streaming
Real-time progress, tool calls, and final results streamed as typed SSE events.
17 Built-in Tools
YouTube, TikTok, Instagram, X/Twitter search & profile tools, Exa.ai neural search, and video analysis.
Pay-per-use
Billed per Gemini call and per third-party tool invocation. No idle cost.
Code Examples
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"
}'
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: <type>\ndata: <json>\n\n"
console.log(text);
}
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 standardevent: / data: SSE format. Each data payload is JSON.
started
Emitted once when the agent session begins.
{
"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.
{
"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.
{
"question": "Which platform would you like to focus on?",
"options": { "...": "..." }
}
tool_call
Emitted when the agent invokes a tool.
{
"tool": "tiktok_search",
"arguments": {
"query": "AI coding tools",
"max_results": 5
}
}
tool_result
Emitted after a tool finishes execution.
{
"tool": "tiktok_search",
"success": true,
"summary": "Found 5 videos"
}
error
Emitted when a step or the entire run encounters a non-fatal error.
{
"message": "Tool tiktok_search failed: rate limited",
"step": 2
}
complete
Final event containing the full structured response. The stream closes after this event.
{
"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_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.
| 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 |
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 | 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 |
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):{
"code": 400,
"message": "query is required"
}
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.
Authorizations
Body
application/json
Natural-language search query
Example:
"Find trending AI coding tool videos on TikTok from the past week"
Restrict to specific platforms. If omitted, all platforms are searched.
Available options:
youtube, tiktok, instagram, twitter Maximum number of video results to return
Recency filter for video results
Available options:
past_24h, past_week, past_month, past_year Maximum agent iteration steps
When true, the agent may return a clarification event instead of searching if the query is ambiguous
Response
SSE stream of agent events (started → progress → tool_call → tool_result → complete)
Unique session identifier
Original user query
Natural-language answer summarizing findings
Structured list of discovered videos
Show child attributes
Show child attributes
Show child attributes
Show child attributes
