---
title: "Search Users"
method: GET
path: "/live/{platform}/search/users"
tags: ["Live Data"]
---

# Search Users

`GET /live/{platform}/search/users`

## Request

- Base URL: `https://viral.app/api/v1`
- URL: `https://viral.app/api/v1/live/{platform}/search/users`
- Auth: API key in header `x-api-key`

Searches accounts on a platform by keyword.

`query` and `pageToken` work the same on every platform. `region` and `language` are hints: applied where a platform's search supports them and ignored elsewhere. The filters of a search route (`sortBy`, `dateRange`, `accountType`) change which results come back, so a platform that cannot apply one refuses the request with a validation error instead of ignoring it.

| Platform | Finds | Pages | Applies | Follower count |
| --- | --- | --- | --- | --- |
| TikTok | accounts | paged | | yes |
| Instagram | accounts | one page | | no |
| YouTube | channels | paged | `region`, `language` | rounded |
| Facebook | pages, or personal profiles with `accountType=person` | paged | `accountType` | no |
| Snapchat | public profiles and accounts | one page | | exact, for public profiles |

Examples:
- `GET /live/tiktok/search/users?query=fitness%20coach`
- `GET /live/youtube/search/users?query=fitness&region=DE&language=de`
- `GET /live/facebook/search/users?query=nike&accountType=page`
- `GET /live/tiktok/search/users?query=nike&accountType=page` is refused with 400: "accountType is supported for Facebook only, where pages and personal profiles are separate searches."

On Facebook and Snapchat a one-word query is also looked up as an exact handle; when that account exists it is the first result, with its full profile. A Facebook result without a vanity name has its numeric id as `username`. A `pageToken` on a platform that has one page returns an empty page and is not charged.

Optional live endpoint. You do not need this endpoint for normal API integrations; prefer tracked accounts, tracked videos, analytics, projects, and Creator Hub endpoints when working with viral.app data.

⚠️ Consumes extra credits: 3 credits per request. Additional charges may apply.

Headers:
- X-Viral-Credits-Consumed
- X-Viral-Credits-Meter
- X-Viral-Credits-Benefited-Remaining
- X-Viral-Credits-Can-Purchase-Extra
- Retry-After (on 429 responses)

A page past the only one of a one-page lookup costs nothing: it carries X-Viral-Credits-Consumed: 0 and X-Viral-Credits-Meter, without the two balance headers.

## Path parameters

- `platform` 'facebook' | 'instagram' | 'tiktok' | 'youtube' | 'snapchat', required: Social media platform (facebook, instagram, tiktok, youtube, snapchat)

## Query parameters

- `query` string, required: Search query string
- `pageToken` string, nullable: Opaque cursor token used to fetch the next page
- `region` string, nullable: Region code (2-letter ISO country code)
- `language` string, nullable: Language code for localized search results (BCP 47 style)
- `accountType` 'page' | 'person', nullable: Facebook only: `page` searches pages (the default), `person` personal profiles. Refused on other platforms.

## Response `200`

OK

- object
  - `users` object[], required
    - `platform` 'facebook' | 'instagram' | 'tiktok' | 'youtube' | 'snapchat', required: Social media platform (facebook, instagram, tiktok, youtube, snapchat)
    - `platform_account_id` string, nullable, required: Native platform account id
    - `username` string, nullable, required
    - `display_name` string, nullable, required
    - `profile_picture_url` string, nullable: URL
    - `is_verified` boolean, nullable, required
    - `is_private` boolean, nullable, required
    - `follower_count` integer, nullable, required
    - `video_count` integer, nullable, required
    - `bio` string, nullable, required
  - `nextPageToken` string, nullable, required

## Other responses

- `400`: 400
- `401`: 401
- `402`: 402
- `403`: 403
- `404`: 404
- `408`: 408
- `429`: 429
- `500`: 500
- `502`: 502

---

[API](https://skmtc.dev/viral/apis/viral-app-api.md) · [All operations](https://skmtc.dev/viral/apis/viral-app-api/llms.txt) · [OpenAPI document](https://skmtc.dev/viral/apis/viral-app-api/revisions/31e97fa79ef1?raw)