# 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 measures how far a video outran its creator's audience: 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`).
- `places` (string[], optional): Beta. Only videos whose creator tagged one of these places on TikTok or Instagram, any of them: a venue, suburb, city, council area or postcode as you would write it (`["chadstone"]`, `["bondi", "manly"]`, `["3000"]`). A word matches as a phrase in the place name or exactly against its suburb, area or postcode. `["*"]` = any tagged place. A tag is the location the creator chose, and about 7% of TikTok and Instagram videos have one (YouTube none). With no topic or look, results include tagged videos Virlo has not analysed yet (`intelligence_status: skipped`). See [Places](https://dev.virlo.ai/docs/places).
- `near` (string[], optional): Beta. Only videos whose tagged place lies within a radius of a map point, any of them. Each item is `"lat,lng,km"`: latitude, longitude and a radius in km from 0.1 to 200, for example `["-37.8136,144.9631,5"]` (5 km around central Melbourne). It reads the tagged place's own map point, so only tagged videos match. Take the point from a place's `lat` and `lng` in [`GET /v1/places`](https://dev.virlo.ai/docs/places#search-places) or from your own geocoder. With `places` too, a video must match both. See [Places](https://dev.virlo.ai/docs/places#near).
- `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.
- `content_types` (string[], optional): `video`, `slideshow` or both. Default `["video"]`. Add `slideshow` for TikTok slideshows (photo carousels); see [Slideshows](https://dev.virlo.ai/docs/search#slideshows).

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",
        "location": null,
        "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. `location` is the place the creator tagged on the post, or `null` (see [Places](https://dev.virlo.ai/docs/places#location-on-videos)).
- `scope`: where the search ran, on every page (cursor pages included).
- `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).
- `slideshows`: only when `content_types` includes `slideshow`. See [Slideshows](https://dev.virlo.ai/docs/search#slideshows).

### Slideshows

Send `content_types: ["slideshow"]` for slideshows only, or `["video", "slideshow"]` for both. Without `content_types` the answer is the same as before, with no `slideshows` field.

**JSON:**

```json
"slideshows": {
  "items": [
    {
      "id": "df3e18c0-d351-4416-a27f-20b2812ce71a",
      "url": "https://www.tiktok.com/@creator/photo/7688190040308075779",
      "views": 47502,
      "virality_score": 21.4,
      "likes": 6341,
      "bookmarks": 1168,
      "images": [{ "image_url": "https://auth.virlo.ai/storage/v1/object/public/slideshow-images/abc.jpg", "position": 0 }],
      "relevance": 3
    }
  ],
  "total": 61,
  "sort_used": "most_viral",
  "not_applied": ["duration: slideshows have no duration"]
}
```

- `items`: up to 25 slideshows, a separate list from `videos`. Each has the same fields as an [agent's slideshows](https://dev.virlo.ai/docs/agents#get-agent-slideshows) (`images` with absolute `image_url`s and their `position`, `author`, `intelligence`, `region`, `is_paid` and the rest), plus `relevance`: `3`, `2`, `1` or `null`, higher is a closer match to the topics.
- `virality_score`: the same Virality Score as on videos (views against the creator's followers; `null` when views did not beat followers), so slideshows and videos can be compared by it.
- Slideshows are ranked by their Virality Score by default (`sort_used: "most_viral"`), or by `most_views` or `newest` when you ask. `rising` has no slideshow score, so it ranks them by views and says so in `not_applied`.
- `not_applied`: the filters in your request that slideshows cannot answer (a duration, for example). The videos keep their own `applied` and `not_applied`.
- `total`: matching slideshows. When `content_types` leaves out `video`, `videos` is `[]`.
- `slideshows` can be `null`: no slideshow list could be built for this request.
- Price unchanged: $0.05 per `virlo_library` page that holds results, videos or slideshows. A page with both costs $0.05, not $0.10.

---

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

### Response fields

- `creators`: up to 25 a page, each with `author_id`, `username`, `display_name`, `platform`, `profile_url`, `avatar_url`, `verified`, `followers`, `bio` and `account_type`.
- `videos_in_virlo`, `recent_videos`: how many of their videos Virlo holds, in all and recently.
- `median_views`, `top_video_views`: their typical video and their biggest one.
- `breakout_videos`: videos that went well past their usual views.
- `last_posted_at`, `main_category`: when they last posted and what they mostly post about.
- `on_topic_videos`: with `topics`, how many of their videos are about them. Otherwise `null`.
- `total`, `page`, `has_more`, `applied`, `not_applied`, `thin`: as on [Search videos](https://dev.virlo.ai/docs/search#search-videos).

**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.
- Bulk copying guard: library pages are for research, not for copying the library. A team that pulls an unusually large share of it in 24 hours (far above any customer's normal use) gets `429` with code `library_quota` and a `Retry-After` header, and that call is not charged. Your own research (`my_research`, `agent`) is never counted. Need bulk data? A [research agent](https://dev.virlo.ai/docs/agents) or a data export is the right fit: email <info@virlo.ai>.
- `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:

- [Places](https://dev.virlo.ai/docs/places.md)
- [Topic Trends](https://dev.virlo.ai/docs/topic-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)
