# Search videos and creators

> Find videos and creators across the Virlo library or your own research by topic, look ("faceless", "talking head"), platform, dates, creator size, views, engagement, Virality Score, region and language. $0.05 per library page of 25.

Source: https://dev.virlo.ai/docs/search
Markdown: https://dev.virlo.ai/docs/search.md
Section: Explore data

## About the Virlo API (applies to every page)

- Base URL: `https://api.virlo.ai/v1`. Every request needs the header `Authorization: Bearer YOUR_API_KEY` (keys start with `virlo_tkn_`).
- Responses are JSON inside a `data` field, except the `/v1/webhooks` endpoints, which return the object or array directly. Field names are snake_case.
- Prices are in US dollars from a prepaid balance. 1 credit = $0.01. The `X-Cost` response header on each successful response is the exact charge. Errors are free.
- Slow jobs return an ID. Check its status every 15 seconds (or whatever `retry_after_seconds` says) until `finalized` is `true`.
- All docs pages: https://dev.virlo.ai/llms.txt. Every page in one file: https://dev.virlo.ai/llms-full.txt. MCP server for AI assistants: https://dev.virlo.ai/api/mcp/mcp.

---

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, an overview of every match (platforms, top creators, formats, hooks, posting weeks, medians), 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](https://dev.virlo.ai/docs/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. For the next page, send the `next_cursor` from the answer as `cursor`: it serves the next page of the same search in the same order, with no repeats or gaps, without running the search again. A cursor lasts 1 hour; an expired or unknown one returns `400` with code `invalid_cursor` (not billed), so run the search again. Video search only; creator pages are always in the same order, so creators keep `page`.
- **`overview`** describes every match, not just the page: the platform split, the creators with the most matching videos, the most common formats and hook types in plain words, matches per week over the last 12 weeks, and median views and Virality Score. It is free and comes on every page, so you can answer about the whole set (how many, which platforms, who, what formats) without paging.

---

## Search videos

**Endpoint:** `POST https://api.virlo.ai/v1/search/videos`

Videos matching a description, ranked. Each video has the same fields as an [agent's videos](https://dev.virlo.ai/docs/agents#get-agent-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

- `scope` (string, optional): `virlo_library`, `my_research` or `agent`. Required unless you send `cursor`.
- `agent_id` (string, optional): With `scope: "agent"`: one of your agents' ids.
- `topics` (string[], optional): Up to 6. One idea each, alternatives joined with `|`. Every item must match.
- `looks_like` (string, optional): What is on screen or how it is made, in plain words. Up to 300 characters.
- `platforms` (string[], optional): `tiktok`, `youtube`, `instagram`. One, or leave it out for all.
- `posted_after` (string, optional): ISO date, `YYYY-MM-DD`.
- `posted_before` (string, optional): ISO date, `YYYY-MM-DD`.
- `creator_followers_min` (integer, optional): The creator's followers, at least.
- `creator_followers_max` (integer, optional): The creator's followers, at most.
- `views_min` (integer, optional): Views, at least.
- `views_max` (integer, optional): Views, at most.
- `likes_min` (integer, optional): Likes, at least.
- `engagement_rate_min` (number, optional): Percent: `5` = 5% ((likes + comments + shares) / views).
- `engagement_rate_max` (number, optional): Percent.
- `virality_min` (number, optional): Virality Score floor, like `18`.
- `outliers_only` (boolean, optional): Only videos that far outperformed their creator's follower count.
- `regions` (string[], optional): Where the video was posted from: ISO 3166 alpha-2 codes (`US`, `GB`, `BR`).
- `languages` (string[], optional): ISO 639-1 codes (`en`, `es`, `pt`).
- `creator_type` (string, optional): `individual` or `brand`.
- `sort` (string, optional): `most_viral` (default), `most_views`, `newest` or `rising` (gaining views fastest right now).
- `page` (integer, optional): Default 1, up to 40.
- `cursor` (string, optional): `next_cursor` from an earlier answer: the next page of that search, same order, without running it again. Send it alone (other fields left out, or the same as the first search). Lasts 1 hour.

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

**cURL request:**

```bash
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:**

```json
{
  "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,
    "cursor": "sc1.4f9a0c1e2b3d4a5f6e7d8c9b0a1f2e3d.1",
    "next_cursor": "sc1.4f9a0c1e2b3d4a5f6e7d8c9b0a1f2e3d.2",
    "applied": ["tiktok", "from 2026-10-01", "prefer: Faceless · Faceless footage", "about: gym/workout", "by virality"],
    "not_applied": [],
    "thin": false,
    "overview": {
      "total": 7602,
      "platforms": [{ "platform": "tiktok", "videos": 7602 }],
      "top_creators": [{ "username": "creator", "platform": "tiktok", "videos": 41 }],
      "formats": [{ "format": "Activity demonstration", "videos": 2911 }, { "format": "Talking head", "videos": 1740 }],
      "hook_types": [{ "hook_type": "Relatable scenario", "videos": 1288 }, { "hook_type": "Bold claim", "videos": 954 }],
      "posted_by_week": [{ "week_start": "2026-10-19", "videos": 912 }, { "week_start": "2026-10-26", "videos": 377 }],
      "posted_earlier": 4120,
      "median_views": 41800,
      "median_virality_score": 14.2
    }
  }
}
```

### 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.
- `cursor`, `next_cursor`: send `next_cursor` as `cursor` for the next page (null on the last page or when nothing matched). `cursor` reads this page again.
- `overview`: every match described (see [How a search works](https://dev.virlo.ai/docs/search#how-it-works)). `posted_by_week` covers the last 12 weeks, oldest first, weeks starting Monday (UTC); `posted_earlier` counts the older matches. Null when nothing matched.
- `applied`, `not_applied`: see [How a search works](https://dev.virlo.ai/docs/search#how-it-works).
- `thin`: fewer than 10 matches. See [Thin results](https://dev.virlo.ai/docs/search#thin-results).

---

## Search creators

**Endpoint:** `POST https://api.virlo.ai/v1/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

- `scope` (string, optional): `virlo_library` (the default and only value today).
- `topics` (string[], optional): What their videos are about, written like video topics.
- `bio_keywords` (string, optional): One word they use for themselves in their bio, like `dermatologist`.
- `platforms` (string[], optional): One platform, or leave it out for all.
- `creator_followers_min` (integer, optional): Followers, at least.
- `creator_followers_max` (integer, optional): Followers, at most.
- `creator_type` (string, optional): `individual` or `brand`.
- `sort` (string, optional): `top_performing` (default: their typical video against their audience size), `rising` (only creators whose typical video beats their follower count) or `most_followers`.
- `page` (integer, optional): Default 1, up to 40.

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

**cURL request:**

```bash
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:**

```json
{
  "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](https://dev.virlo.ai/docs/agents) 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.

**JSON:**

```json
"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, or a video `cursor` that is unknown, expired (1 hour) or sent with a different search (code `invalid_cursor`, not billed: run the search again). `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.

---

More in Explore data:

- [Pop culture & News](https://dev.virlo.ai/docs/trends.md)
- [Content Trends](https://dev.virlo.ai/docs/content-trends.md)
- [Sounds](https://dev.virlo.ai/docs/sounds.md)
- [Hooks](https://dev.virlo.ai/docs/hooks.md)
- [Hashtags](https://dev.virlo.ai/docs/hashtags.md)
- [Videos](https://dev.virlo.ai/docs/videos.md)
- [Raw data](https://dev.virlo.ai/docs/raw.md)
- [Raw Meta ads](https://dev.virlo.ai/docs/raw/meta-ads.md)