Search videos and creators

Describe the videos or creators you want and get a ranked page back: "the most viral Reels about skincare from creators with 1k to 100k followers", "faceless gym videos on TikTok this month", "UGC skincare creators".

At a glance

What it does: Searches the videos Virlo has analysed (or your own research) and the creators behind them, with the same search engine the Virlo app's Copilot uses.
You send: Where to search, plus any of: topics, what the video looks like in plain words, platform, dates, creator followers, views, engagement, Virality Score, region, language and account type.
You get back: Within seconds, 25 videos or creators a page, the total, and which of your filters were applied and which were not, in plain words.
Cost: $0.05 per page of 25 from the Virlo library. An empty page is free. Searching your own research is free.

Where to search

virlo_library: every video Virlo has analysed, across all customers' research and Virlo's own collection. $0.05 per page.
my_research: the videos your team's research agents collected. Free.
agent: one of your agents, named by agent_id. Free. An id that is not one of your team's agents returns 404.

Creator search covers the library only.

How a search works

Topics are what the content is about. Write one item per idea and join alternatives for the same idea with |: ["skin barrier|barrier repair", "morning routine"] means (skin barrier or barrier repair) and morning routine. English words match best.
looks_like is what is on screen or how the video is made, in plain words: faceless, talking head, UGC, no AI, girl dancing in her bedroom. Virlo matches the words to what its video analysis can see. Most looks rank matching videos first (applied shows them as prefer: ...) without dropping the rest; "only" in your words (only UGC) makes it a filter.
applied lists what the search used, in plain words, for example ["tiktok", "from 2026-10-01", "prefer: Faceless", "about: gym/workout", "by virality"]. not_applied lists what it could not use: a filter it widened because too few videos matched, two of three platforms (search one platform or all), or looks_like words it did not recognise.
Ranking is by Virality Score unless you pick another sort. The Virality Score is ln(views / followers) x ln(followers): 10 promising, 18 strong, 25 very strong, 35 exceptional. It compares videos fairly across creator sizes and platforms, raw views do not.
Pages are 25 items. Ask for page 2 the same way with page: 2; the order stays the same.

POST/v1/search/videos

Search videos

Videos matching a description, ranked. Each video has the same fields as an agent's videos, plus virality_score.

Cost: $0.05 per virlo_library page that holds results. An empty page and the my_research and agent scopes are free.

Body

Name
scope
Type
string
Description
Required. virlo_library, my_research or agent.
Name
agent_id
Type
string
Description
With scope: "agent": one of your agents' ids.
Name
topics
Type
string[]
Description
Up to 6. One idea each, alternatives joined with |. Every item must match.
Name
looks_like
Type
string
Description
What is on screen or how it is made, in plain words. Up to 300 characters.
Name
platforms
Type
string[]
Description
tiktok, youtube, instagram. One, or leave it out for all.

An unknown field returns 400. A virlo_library search with nothing to narrow it (no topic, look, date window, platform or region) returns 400.

Request

POST

/v1/search/videos

curl -X POST "https://api.virlo.ai/v1/search/videos" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "scope": "virlo_library",
    "topics": ["gym|workout"],
    "looks_like": "faceless",
    "platforms": ["tiktok"],
    "posted_after": "2026-10-01"
  }'

Response

{
  "data": {
    "videos": [
      {
        "id": "5b18065a-d4f1-4bb4-9de0-4c8a30298b1f",
        "url": "https://www.tiktok.com/@creator/video/7561234567890123456",
        "description": "POV: the last set before rest day",
        "platform": "tiktok",
        "views": 2344734,
        "likes": 312000,
        "shares": 9100,
        "comments": 1830,
        "bookmarks": 40210,
        "publish_date": "2026-10-09T18:22:41Z",
        "duration": 14,
        "virality_score": 53.3,
        "author": {
          "username": "creator",
          "avatar_url": "https://auth.virlo.ai/storage/v1/object/public/avatars/abc.jpg",
          "followers": 8200,
          "verified": false
        },
        "hashtags": ["gymtok", "fitness"],
        "thumbnail_url": "https://auth.virlo.ai/storage/v1/object/public/thumbnails/abc.jpg",
        "is_duet": false,
        "is_stitch": false,
        "is_paid": false,
        "paid_signals": [],
        "upload_region": "US",
        "intelligence": {
          "primary_topic": "gym motivation",
          "content_format": "trend_performance",
          "hook_type": "relatable_moment",
          "setting": "gym",
          "summary": "Faceless clip of a heavy set with on-screen text"
        },
        "intelligence_status": "ready",
        "sound": null
      }
    ],
    "total": 7602,
    "page": 1,
    "has_more": true,
    "applied": ["tiktok", "from 2026-10-01", "prefer: Faceless · Faceless footage", "about: gym/workout", "by virality"],
    "not_applied": [],
    "thin": false
  }
}

Response fields

videos: up to 25. intelligence holds readable values from Virlo's video analysis; a value the analysis was not sure of is null, and intelligence_status: "skipped" means the video was not analysed. With my_research or agent, each video also has agent_id, the agent that collected it.
total: matching videos in the scope. has_more: another page exists.
applied, not_applied: see How a search works.
thin: fewer than 10 matches. See Thin results.

POST/v1/search/creators

Search creators

Creators across the Virlo library, by what their videos are about, a word in their bio, platform, followers and account type.

Cost: $0.05 per page that holds results. An empty page is free.

Body

Name
scope
Type
string
Description
virlo_library (the default and only value today).
Name
topics
Type
string[]
Description
What their videos are about, written like video topics.
Name
bio_keywords
Type
string
Description
One word they use for themselves in their bio, like dermatologist.
Name
platforms
Type
string[]
Description
One platform, or leave it out for all.
Name
creator_followers_min
Type
integer
Description
Followers, at least.

A search needs topics, bio_keywords or creator_type; without one it returns 400.

Request

POST

/v1/search/creators

curl -X POST "https://api.virlo.ai/v1/search/creators" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "topics": ["skincare|skin care"],
    "creator_type": "individual",
    "creator_followers_min": 1000,
    "creator_followers_max": 100000
  }'

Response

{
  "data": {
    "creators": [
      {
        "author_id": "0b6d2f4e-1c2a-4f6e-9d1b-7e2a5c3f9a10",
        "username": "creator",
        "display_name": "Creator",
        "platform": "tiktok",
        "profile_url": "https://www.tiktok.com/@creator",
        "avatar_url": "https://auth.virlo.ai/storage/v1/object/public/avatars/def.jpg",
        "verified": false,
        "followers": 7206,
        "bio": "skincare for sensitive skin",
        "account_type": "individual",
        "videos_in_virlo": 41,
        "recent_videos": 12,
        "median_views": 1022346,
        "top_video_views": 6100000,
        "last_posted_at": "2026-10-26T15:02:11Z",
        "breakout_videos": 9,
        "main_category": "beauty",
        "on_topic_videos": 3
      }
    ],
    "total": 1058,
    "page": 1,
    "has_more": true,
    "applied": ["about: skincare / skin care", "at least 1,000 followers", "at most 100,000 followers", "account: individual", "by top performing"],
    "not_applied": [],
    "thin": false
  }
}

Thin results

Under 10 matches, thin is true: Virlo has not collected that topic well yet. A thin video search also returns next_step, a ready request for a one-time research agent that collects fresh videos on the topic, with its price. Nothing is started for you: send it to POST /v1/agents only when you or your user want it.

"next_step": {
  "action": "start_research_agent",
  "endpoint": "POST /v1/agents",
  "body": { "is_recurring": false, "intent": "axolotl", "keywords": ["axolotl"], "platforms": ["instagram"] },
  "price_credits": 50,
  "price": "$0.50",
  "time": "about 8 minutes"
}

Costs and errors

virlo_library videos and creators: $0.05 (5 credits) per page of up to 25 that holds results. Page 2 costs the same as page 1. An empty page costs nothing. The X-Cost header on each response is the exact charge.
my_research and agent: free.
400: invalid fields, a library search with nothing to narrow it, or a creator search without topics, bio_keywords or creator_type. 402: not enough credits for a library page. 404: agent_id is not one of your agents. 503 / 504: the search did not answer in time; nothing is charged.