Skip to main content

​
Overview

The Username Search API allows you to check username availability across hundreds of social media platforms and websites using multiple OSINT data sources.
This endpoint uses Server-Sent Events (SSE) streaming to provide real-time progress updates as each source is checked.

​
Endpoint

POST /api/username/search

​
Available Sources

Cross-platform username search with comprehensive site coverage.Coverage: 500+ platforms
Speed: Fast parallel checking

​
Request

​
Headers

Content-Type: application/json

​
Body Parameters

​
username
string
required
The username to search for. Must be at least 1 character long.Will be automatically trimmed and converted to lowercase.Example: "john_doe"
​
sources
string[]
Array of OSINT sources to use. If omitted, all sources will be queried.Valid values: "whatsmyname", "sherlock", "maigret"Default: All sourcesExample: ["whatsmyname", "sherlock"]

​
Request Example

curl -X POST http://localhost:3000/api/username/search \
  -H "Content-Type: application/json" \
  -d '{
    "username": "john_doe",
    "sources": ["whatsmyname", "sherlock"]
  }'

​
Response

The endpoint returns a Server-Sent Events (SSE) stream with Content-Type: text/event-stream.

​
Event Types

​
progress
object
Progress update during username checking
​
result
object
Individual site check result
​
complete
object
Final event indicating all checks are complete
​
error
object
Error event if something goes wrong

​
Response Example

{
  "type": "progress",
  "data": {
    "total": 500,
    "checked": 125,
    "found": 12,
    "source": "whatsmyname"
  }
}

​
Get Available Sources

You can also retrieve the list of available OSINT sources: 
GET /api/username/search

​
Response

{
  "sources": [
    {
      "id": "whatsmyname",
      "name": "WhatsMyName",
      "description": "Cross-platform username search"
    },
    {
      "id": "sherlock",
      "name": "Sherlock",
      "description": "Hunt usernames across social networks"
    },
    {
      "id": "maigret",
      "name": "Maigret",
      "description": "Collect dossier on a person by username"
    }
  ]
}

​
Error Responses

​
400
Invalid username
{
  "error": "Invalid username"
}
​
400
No valid sources
{
  "error": "No valid sources selected"
}
​
500
Server error
{
  "error": "Server error"
}

​
Source Code Reference

The implementation can be found at:
  • API Route: source/app/api/username/search/route.ts:8
  • Username Checker: source/lib/username/checker.ts
  • Type Definitions: source/lib/username/types/

​
Best Practices

Rate Limiting: Username searches can be resource-intensive. Implement rate limiting to prevent abuse.
Caching: Consider caching results for frequently searched usernames to reduce load.

​
Recommendations

  1. Start with fewer sources: Use ["whatsmyname"] for faster results
  2. Handle timeouts: Some sites may be slow or unresponsive
  3. Filter results: Focus on high-confidence matches (status: “found”)
  4. Respect privacy: Use this tool responsibly and ethically

​
Example Implementation

interface CheckResult {
  site: string;
  source: string;
  url: string;
  status: 'found' | 'not_found' | 'error' | 'checking';
  statusCode?: number;
  responseTime?: number;
  category?: string;
}

async function searchUsername(username: string) {
  const results: CheckResult[] = [];
  
  const response = await fetch('/api/username/search', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ 
      username,
      sources: ['whatsmyname', 'sherlock']
    })
  });

  const reader = response.body!.getReader();
  const decoder = new TextDecoder();

  while (true) {
    const { done, value } = await reader.read();
    if (done) break;

    const text = decoder.decode(value);
    const lines = text.split('\n');

    for (const line of lines) {
      if (line.startsWith('data: ')) {
        const event = JSON.parse(line.slice(6));
        
        if (event.type === 'result') {
          results.push(event.data.result);
        } else if (event.type === 'progress') {
          console.log(`Progress: ${event.data.checked}/${event.data.total}`);
        }
      }
    }
  }

  return results.filter(r => r.status === 'found');
}

Build docs developers (and LLMs) love

Get started for freeTalk to us