---
title: "Search Viral Outlier Posts"
method: POST
path: "/api/v1/search/content"
---

# Search Viral Outlier Posts

`POST /api/v1/search/content`

## Request

- Base URL: `https://viraloutliers.com`
- URL: `https://viraloutliers.com/api/v1/search/content`
- Auth: HTTP bearer

Search a continuously-crawled database of social media posts ranked by outlier score: how strongly a post overperforms the account's own baseline. Filter by platform, keyword, exact creator handle, content type, an outlier-score band (min/max), a view band (min/max), a follower band (min/max), an engagement-rate band (min/max) and time window; sort by outlier score, views, likes, engagement or recency. Returns post metadata, stats and thumbnails. Use this to find proven viral formats in any niche before creating content. Results may include deleted posts (deleted_at set) and posts from deactivated profiles (profile is_active=false), these are kept for their thumbnails and format ideas, with stats frozen at deletion; filter on deleted_at / is_active if you only want live content.

Cost: 1 credit per 25 posts returned.

## Request body

- object
  - `query` string: Keyword search over captions/titles/handles.
  - `platforms` string[]: "tiktok" | "instagram" | "youtube".
  - `handle` string: Exact creator handle (without @). Pins results to one account; takes precedence over the free-text query.
  - `watchlistId` string: Scope the search to the creators in one of your watchlists (id from list_watchlists / create_watchlist). Combine with any other filter.
  - `categoryId` string: Niche filter: a category id from list_categories. Covers the whole subtree (a Level 2 niche includes its sub-niches). Ignored when handle or watchlistId is set.
  - `contentTypes` string[]: Content types to include, case-insensitive. TikTok: Video, Photo (slideshow). Instagram: Video (reel), Image, Carousel. YouTube: Video, Short, Live.
  - `minOutlierScore` number: Only posts overperforming their account baseline by at least this factor.
  - `maxOutlierScore` number: Upper bound on outlier score, e.g. exclude extreme one-off spikes.
  - `minViews` number: Minimum view count.
  - `maxViews` number: Maximum view count.
  - `minFollowers` number: Floor on account size, e.g. exclude tiny/brand-new accounts.
  - `maxFollowers` number: Cap account size, find small accounts with huge posts.
  - `minEngagementRate` number: Minimum engagement rate, as a fraction of views: (likes+comments)/views. So 0.04 means 4%.
  - `maxEngagementRate` number: Maximum engagement rate, same fraction scale (0.04 = 4%).
  - `timeFrame` string: "one_week" | "one_month" | … | "all_time".
  - `sortBy` string: Sort key: outlier/views/likes/date/engagement, each _desc or _asc (default outlier_desc).
  - `page` number: Page number, 1-based. A search serves its first 1,000 posts; a page past that is refused at no charge, so narrow the filters instead.
  - `pageSize` number: Results per page, 1 to 100 (default 25). Billed per 25 posts returned: 25 costs 1 credit, 100 costs 4.

## Response `200`

Success

- object

## Other responses

- `401`: Invalid or revoked API key (or, on free skills, no key sent); code key_suspended means the key was suspended when its account was claimed by the email owner and can be reactivated in Settings
- `402`: Payment required. Without an API key (billable skills only) the code is payment_required and error.payment.checkoutUrl (or, when no link is configured, error.payment.pageUrl at https://viraloutliers.com/api-access) buys a key without an account; with a key it is insufficient_credits and error.payment points at create_topup_link.
- `429`: Rate limited

---

[API](https://skmtc.dev/viraloutliers/apis/viral-outliers-agent-api.md) · [All operations](https://skmtc.dev/viraloutliers/apis/viral-outliers-agent-api/llms.txt) · [OpenAPI document](https://skmtc.dev/viraloutliers/apis/viral-outliers-agent-api/revisions/0099977bd629?raw)