---
title: "Search Social Media Profiles"
method: POST
path: "/api/v1/search/profiles"
---

# Search Social Media Profiles

`POST /api/v1/search/profiles`

## Request

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

Search tracked social media profiles by handle or name, filtered by platform. Returns profile metadata, follower counts and average performance stats. Use it to resolve a handle to a profile id before fetching stats or posts, or to discover creators in the database. Results may include deactivated profiles (is_active=false), e.g. an account that was renamed or went private, retained with frozen stats; filter on is_active if you only want live accounts. Note a creator who changed handles can appear as two rows (old deactivated + new active).

Cost: 1 credit per 25 profiles returned.

## Request body

- object
  - `query` string: Handle or name fragment.
  - `platforms` string[]: "tiktok" | "instagram" | "youtube".
  - `categoryId` string: Niche filter: a category id from list_categories (covers its subtree). Without a query this returns the niche's top profiles by followers.
  - `page` number: Page number, 1-based. A search serves its first 1,000 profiles; 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 profiles 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)