Video Searching API - Memories.ai API Tools

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.

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"
  }'

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.

{
  "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	`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

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. 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

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):

{
  "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.

Authorizations

Authorization

string

header

required

Body

application/json

query

string

required

Natural-language search query

Example:

"Find trending AI coding tool videos on TikTok from the past week"

platforms

enum<string>[]

Restrict to specific platforms. If omitted, all platforms are searched.

Available options:

youtube,

tiktok,

instagram,

twitter

max_results

integer

default:10

Maximum number of video results to return

time_frame

enum<string>

Recency filter for video results

Available options:

past_24h,

past_week,

past_month,

past_year

max_steps

integer

default:10

Maximum agent iteration steps

enable_clarification

boolean

default:false

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)

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

Show child attributes

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

Show child attributes

Video Agents

SSE Streaming

17 Built-in Tools

Pay-per-use

​Code Examples

​SSE Event Types

​started

​progress

​clarification

​tool_call

​tool_result

​error

​complete

​Response Fields

​Top-level

​VideoRef

​Available Tools

​Billing & Cost Breakdown

​Gemini Model (Token-based)

​Social Platform Search Tools

​Creator / Profile Tools

​Exa.ai Tools

​YouTube Tools — Free

​Video Analysis Tools — Billed by Underlying Service

​Cost Example

​Error Handling

​Rate Limits

Authorizations

Body

Response

Code Examples

SSE Event Types

`started`

`progress`

`clarification`

`tool_call`

`tool_result`

`error`

`complete`

Response Fields

Top-level

VideoRef

Available Tools

Billing & Cost Breakdown

Gemini Model (Token-based)

Social Platform Search Tools

Creator / Profile Tools

Exa.ai Tools

YouTube Tools — Free

Video Analysis Tools — Billed by Underlying Service

Cost Example

Error Handling

Rate Limits