api / json over https, bearer key
Username lookup API
The UsernameLookup API is a REST interface that checks a username on 300+ public sites and returns, as JSON, which sites have a profile, the profile links, response times and a confidence score. A second endpoint checks availability on platforms and 25 domain extensions.
Three endpoints cover lookups and availability
The base address is https://usernamelookup.com/api/v1. Every request is a GET with your key in the Authorization header. Responses are JSON in UTF-8.
| Endpoint | What it returns | Counts toward quota |
|---|---|---|
| GET /api/v1/username/{username} | Live lookup across every site: found, free or unknown per site, profile URL, response time, first seen, confidence. | yes |
| GET /api/v1/lookups/{id} | The same lookup by id, for polling while sites are still answering. | no |
| GET /api/v1/availability/{name} | Free, taken or unknown on the main platforms, plus 25 domain extensions checked through DNS and RDAP. | yes |
Optional query parameters on the username endpoint: categories (comma list of social, video, dev, gaming, forums, marketplaces) and wait (0 to 25 seconds, default 20). Usernames are 2 to 50 letters, digits, dots, underscores or hyphens.
A lookup request and its JSON answer
Send the key as a bearer token. The response lists every site that was checked. Only found sites carry a profile URL.
request
curl https://usernamelookup.com/api/v1/username/janedoe?categories=social,dev \ -H "Authorization: Bearer ul_live_your_key" \ -H "Accept: application/json"
availability request
curl https://usernamelookup.com/api/v1/availability/northwind \ -H "Authorization: Bearer ul_live_your_key"
response 200
{
"id": "lk_8f3k2m9q",
"username": "janedoe",
"status": "done",
"sites_total": 214,
"sites_checked": 214,
"found_count": 2,
"confidence": {
"score": 72,
"reasons": ["same display name on 2 sites", "cross link between profiles"]
},
"sites": [
{
"site": "GitHub",
"slug": "github",
"category": "dev",
"status": "found",
"profile_url": "https://github.com/janedoe",
"response_ms": 412,
"first_seen": "2026-09-14T08:12:44+00:00"
},
{
"site": "Reddit",
"slug": "reddit",
"category": "forums",
"status": "free",
"profile_url": null,
"response_ms": 388,
"first_seen": null
}
],
"poll_url": null
}
Example values. The sites list is shortened here.
Availability in one call
The availability endpoint answers the naming question: where can this name still be registered. Platforms come back as free, taken or unknown with the profile address, and each domain extension has an available flag and the time it was checked.
Use it in a signup flow to suggest free handles, in a naming tool, or in a brand registration checklist. The same data powers the domain and username checker on the site.
{
"name": "northwind",
"platforms": [
{ "platform": "Instagram", "slug": "instagram", "available": false,
"status": "taken", "url": "https://www.instagram.com/northwind/" },
{ "platform": "TikTok", "slug": "tiktok", "available": true,
"status": "free", "url": "https://www.tiktok.com/@northwind" }
],
"domains": [
{ "domain": "northwind.com", "available": false, "checked_at": "2026-10-10T09:00:12+00:00" },
{ "domain": "northwind.io", "available": true, "checked_at": "2026-10-10T09:00:12+00:00" }
],
"usage": { "api_calls_used": 128, "api_calls_limit": 10000 }
}
Error codes and what to do about them
Errors return a JSON body with an error code and a readable message. Branch on the code, not the message text.
| HTTP | error | Meaning | What to do |
|---|---|---|---|
| 401 | unauthenticated | No Authorization header was sent. | Send "Authorization: Bearer" with your key. |
| 401 | invalid_key | The key does not exist or was revoked. | Create a new key in the dashboard. |
| 402 | plan_required | The workspace has no active paid plan. | Renew or choose a plan. |
| 404 | not_found | No lookup with this id in your workspace. | Check the id from the first response. |
| 422 | invalid_username | The name breaks the 2 to 50 character rule. | Strip spaces and unsupported characters. |
| 429 | rate_limited | Too many requests for this key in the current minute. | Wait the seconds in the Retry-After header. |
| 429 | quota_exceeded | The monthly API calls of the plan are used up. | Wait for the next period or upgrade the plan. |
API limits on each plan
Monthly calls count usage in the billing period and reset with the next period. There are no overage charges: at the limit the API answers 429 until the period resets or you move to a larger plan. Every response from the availability endpoint carries your current usage.
| Plan | Calls per month | Requests per minute per key | Confidence score | Price billed yearly |
|---|---|---|---|---|
| Pro | 1,000 | 30 | no | $24 / month |
| Investigator | 10,000 | 60 | yes | $74 / month |
| Brand Monitoring | 50,000 | 120 | yes | $249 / month |
| Brand Enterprise | 500,000 | 600 | yes | $999 / month |
Monthly prices are $49, $149, $499 and $1,999. Full details on username lookup pricing.
Where teams plug the API in
Signup risk checks
Look up the handle a new user picks and flag names that copy a known brand or have no public footprint at all. See username verification for KYC.
Investigation tooling
Pull lookups into your case system so every analyst sees the same results, history and profile links. Related: OSINT username search.
Brand protection pipelines
Combine scheduled lookups of your handles with monitoring webhooks to route new fake account detection findings to tickets.
The API checks public profile addresses only and respects the opt-out list: a username that was removed by its owner returns status not_searchable. Our acceptable use policy applies to API results the same way it applies to the dashboard.
Questions about the username lookup API
How do I get an API key?
Choose any paid plan, open the dashboard and create a key under API keys. The key is shown once, so store it in your secret manager. You can revoke a key and create a new one at any time.
Why does the username endpoint sometimes return 202?
A full lookup checks 300+ sites live. The call waits up to 25 seconds (set with the wait parameter) and returns 200 when every site has answered. If some are still running you get 202 with partial results and a poll_url. Polling an existing lookup is free and does not use your monthly quota.
What counts as one API call?
One served request to the username or availability endpoint. Polling a lookup by id does not count. Rejected requests, such as an invalid username, do not count either. Deleting lookups never gives quota back.
Is the confidence score included on every plan?
The confidence object with score and reasons is filled on the Investigator plan and above. On Pro the field is null and the rest of the response is identical.
Can I receive monitoring alerts in my own system?
Yes. Add a webhook endpoint as an alert channel. Each delivery is a JSON body signed with HMAC SHA-256 over the timestamp and body, sent in the X-UsernameLookup-Signature header together with X-UsernameLookup-Timestamp.
Try a lookup before you write code
Run one search in the browser to see the data the API returns for 300+ sites.