---
title: "Search a username across the web"
method: POST
path: "/usernames/search"
tags: ["Usernames"]
---

# Search a username across the web

`POST /usernames/search`

## Request

- Base URL: `https://api.socially.run/v1`
- URL: `https://api.socially.run/v1/usernames/search`
- Auth: HTTP bearer

Sweep the site database for one handle and report every site's answer: found, notFound, or undecided when the site could not be read. Answers 202 with a job. Stream it or poll get_job. An identical search already running returns that same job and costs nothing.

## Request body

- object
  - `username` string, required: The handle to look for. Letters, digits, dot, dash and underscore.
  - `tier` 'fast' | 'full': fast sweeps the top-ranked sites inside a minute (5 credits); full sweeps the whole database (20 credits).
  - `categories` string[]: Only sweep sites in these categories.
  - `sites` string[]: Only sweep these site ids (from list_username_sites).
  - `countries` string[]: Only sweep sites that serve these countries (ISO 3166-1 alpha-2). A site is kept when it serves any of them.
  - `includeNsfw` boolean: Include sites marked as adult. Requires a plan that allows them.
  - `includeUnreliable` boolean: Also sweep sites the nightly check distrusts. They answer, but never above low confidence.

## Response `202`

Search a username across the web

- object
  - `data` unknown, required

## Other responses

- `400`: VALIDATION_ERROR / INVALID_TARGET / SSRF_BLOCKED: the issues, never the values.
- `401`: UNAUTHORIZED / INVALID_TOKEN: the key is missing or wrong.
- `402`: PAYMENT_REQUIRED / PLAN_GATE: clears by upgrading or buying credits, never by waiting.
- `429`: RATE_LIMIT_EXCEEDED / QUOTA_EXCEEDED: Retry-After says when it clears.
- `default`: Any other failure.

---

[API](https://skmtc.dev/socially/apis/socially-run-send-a-profile-link-get-its-public-data-as-json.md) · [All operations](https://skmtc.dev/socially/apis/socially-run-send-a-profile-link-get-its-public-data-as-json/llms.txt) · [OpenAPI document](https://skmtc.dev/socially/apis/socially-run-send-a-profile-link-get-its-public-data-as-json/revisions/5a0b24534b90?raw)