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.

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.

{
  "users": [
    {
      "platform": "facebook",
      "platform_account_id": "7123456789012345678",
      "profile_picture_url": "https://www.myproject.com"
    }
  ]
}