# sociallinks.dev API

One creator profile in, every account out. Send an Instagram, TikTok, YouTube or X profile URL; get the creator's accounts on the other platforms, each with a verdict, a net confidence score (0–1) and evidence.

Base URL: https://sociallinks.dev/v1
Auth: `Authorization: Bearer sl_…` (or `x-api-key: sl_…`). Create keys at https://sociallinks.dev/dashboard/api#api-keys.
Billing: 1 credit per creator when at least one account is found; nothing found and failed lookups are free; repeats by the same account within 30 days are free.
Errors: `{ "error": { "message", "code" } }`. OpenAPI 3.1: https://sociallinks.dev/openapi.json

## Look up a creator
`POST https://sociallinks.dev/v1/resolve`

Send one Instagram, TikTok, YouTube or X profile URL. You get the creator's accounts on the other platforms, each with a verdict, a net confidence score and the evidence behind it. Fresh lookups take 10–40 seconds; creators we already have come back instantly. 1 credit when at least one account is found; nothing found is free. The X-Credits-Remaining header carries your balance.

Parameters:
- `url` (body, string, required): A creator's profile page. Posts, reels, videos and bare @handles are refused with 400.

Example:
```bash
curl -X POST "https://sociallinks.dev/v1/resolve" \
  -H "Authorization: Bearer $SOCIALLINKS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://www.instagram.com/mkbhd"}'
```

Response (200):
```json
{
  "creator": {
    "id": "cr_0k3x9a1",
    "name": "Marques Brownlee",
    "kind": "person",
    "aliases": ["Marques Brownlee", "mkbhd"],
    "total_audience": 38000000
  },
  "profiles": [
    { "platform": "instagram", "handle": "mkbhd", "verdict": "seed", "net_confidence": 1 },
    {
      "platform": "youtube",
      "handle": "mkbhd",
      "url": "https://www.youtube.com/@mkbhd",
      "followers": 20000000,
      "verdict": "confirmed",
      "net_confidence": 0.97,
      "evidence": [
        { "kind": "bio_link", "detail": "Linked from the creator's own Instagram bio", "source": "https://www.instagram.com/mkbhd" }
      ]
    }
  ],
  "websites": [{ "url": "https://mkbhd.com", "kind": "website", "label": "mkbhd.com" }],
  "identity_confidence": 0.96,
  "rejected": 4
}
```

## Look up a creator (GET)
`GET https://sociallinks.dev/v1/resolve`

Identical to POST /resolve, for tools that can only send GET requests.

Parameters:
- `url` (query, string, required): A creator's profile page, URL-encoded.

Example:
```bash
curl "https://sociallinks.dev/v1/resolve?url=https%3A%2F%2Fwww.instagram.com%2Fmkbhd" \
  -H "Authorization: Bearer $SOCIALLINKS_KEY"
```

Response (200):
```json
{
  "creator": {
    "id": "cr_0k3x9a1",
    "name": "Marques Brownlee",
    "kind": "person",
    "aliases": ["Marques Brownlee", "mkbhd"],
    "total_audience": 38000000
  },
  "profiles": [
    { "platform": "instagram", "handle": "mkbhd", "verdict": "seed", "net_confidence": 1 },
    {
      "platform": "youtube",
      "handle": "mkbhd",
      "url": "https://www.youtube.com/@mkbhd",
      "followers": 20000000,
      "verdict": "confirmed",
      "net_confidence": 0.97,
      "evidence": [
        { "kind": "bio_link", "detail": "Linked from the creator's own Instagram bio", "source": "https://www.instagram.com/mkbhd" }
      ]
    }
  ],
  "websites": [{ "url": "https://mkbhd.com", "kind": "website", "label": "mkbhd.com" }],
  "identity_confidence": 0.96,
  "rejected": 4
}
```

## Look up many creators
`POST https://sociallinks.dev/v1/batches`

Each row is charged only when it finds accounts, and rows your account paid for in the last 30 days are free. Rows that aren't profile links are skipped and never charged. Poll the batch, then download the CSV.

Parameters:
- `urls` (body, string[] | string, required): Up to 500 profile URLs, as an array or one per line.
- `name` (body, string): A label for the batch.

Example:
```bash
curl -X POST "https://sociallinks.dev/v1/batches" \
  -H "Authorization: Bearer $SOCIALLINKS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Q4 shortlist","urls":["https://www.tiktok.com/@zachking","https://www.youtube.com/@mkbhd"]}'
```

Response (201):
```json
{
  "id": "6f1c2a4e-1b2c-4d3e-9f00-0a1b2c3d4e5f",
  "rows": 2,
  "invalid": 0,
  "duplicates": 0
}
```

## Check a batch
`GET https://sociallinks.dev/v1/batches/{id}`

Poll every few seconds until status is "completed", "partial" or "failed". Each item carries its own status and the accounts found.

Parameters:
- `id` (path, uuid, required): The id POST /batches returned.

Example:
```bash
curl "https://sociallinks.dev/v1/batches/$BATCH_ID" \
  -H "Authorization: Bearer $SOCIALLINKS_KEY"
```

Response (200):
```json
{
  "batch": {
    "id": "6f1c2a4e-1b2c-4d3e-9f00-0a1b2c3d4e5f",
    "name": "Q4 shortlist",
    "status": "completed",
    "total": 2,
    "succeeded": 2,
    "empty": 0,
    "failed": 0,
    "skipped": 0,
    "charged": 2,
    "created_at": "2026-10-19T09:30:00Z"
  },
  "items": [
    {
      "position": 0,
      "input": { "url": "https://www.tiktok.com/@zachking" },
      "status": "succeeded",
      "charged": 1,
      "result": {
        "name": "Zach King",
        "profiles": [{ "platform": "youtube", "handle": "ZachKing", "url": "https://www.youtube.com/@ZachKing", "verdict": "confirmed" }],
        "notFound": ["linkedin"]
      }
    }
  ]
}
```

## Download a batch as CSV
`GET https://sociallinks.dev/v1/batches/{id}/export`

Ready for a spreadsheet or a CRM import.

Parameters:
- `id` (path, uuid, required): The batch id.

Example:
```bash
curl "https://sociallinks.dev/v1/batches/$BATCH_ID/export" \
  -H "Authorization: Bearer $SOCIALLINKS_KEY" -o results.csv
```

Response (200):
```csv
row,input,status,credits,creator,verified_creator,instagram,youtube,tiktok,x,twitch,facebook,linkedin,nothing_found_on,error
1,https://www.tiktok.com/@zachking,succeeded,1,Zach King,no,https://www.instagram.com/zachking,https://www.youtube.com/@ZachKing,https://www.tiktok.com/@zachking,https://x.com/zachking,,https://www.facebook.com/zachking,,linkedin,
```

## List your batches
`GET https://sociallinks.dev/v1/batches`

Handy for picking up where you left off.

Parameters:
- none

Example:
```bash
curl "https://sociallinks.dev/v1/batches" \
  -H "Authorization: Bearer $SOCIALLINKS_KEY"
```

Response (200):
```json
{
  "batches": [
    {
      "id": "6f1c2a4e-1b2c-4d3e-9f00-0a1b2c3d4e5f",
      "name": "Q4 shortlist",
      "status": "completed",
      "total": 2,
      "succeeded": 2,
      "empty": 0,
      "failed": 0,
      "skipped": 0,
      "charged": 2,
      "created_at": "2026-10-19T09:30:00Z"
    }
  ]
}
```

## Stop a batch
`POST https://sociallinks.dev/v1/batches/{id}/cancel`

Rows already running finish. Returns 409 if the batch has already finished.

Parameters:
- `id` (path, uuid, required): The batch id.

Example:
```bash
curl -X POST "https://sociallinks.dev/v1/batches/$BATCH_ID/cancel" \
  -H "Authorization: Bearer $SOCIALLINKS_KEY"
```

Response (200):
```json
{ "ok": true }
```

## Check your balance
`GET https://sociallinks.dev/v1/balance`

The same credits the website uses. Buy packs at https://sociallinks.dev/pricing.

Parameters:
- none

Example:
```bash
curl "https://sociallinks.dev/v1/balance" \
  -H "Authorization: Bearer $SOCIALLINKS_KEY"
```

Response (200):
```json
{ "credits": 742 }
```

## MCP server
Add https://sociallinks.dev/mcp to any MCP client as a Streamable HTTP server, with the API key in the Authorization header. Tools are charged exactly like the REST endpoints.

- `lookup_creator`: Find a creator's accounts on the other platforms from one Instagram, TikTok, YouTube or X profile URL. Returns the creator, each account with its verdict, net confidence (0–1) and evidence, and any websites. 1 credit when at least one account is found; free otherwise.
- `check_balance`: Credits left on the account behind the API key. Free.
- `start_batch`: Queue up to 500 profile URLs to look up in the background. Returns a batch id; poll it with get_batch. Each row is charged only if it finds accounts.
- `get_batch`: Progress and the rows found so far for a batch started with start_batch.

### Claude Code (Terminal)

```
claude mcp add --transport http sociallinks https://sociallinks.dev/mcp --header "Authorization: Bearer sl_your_key"
```

### Cursor (~/.cursor/mcp.json)

```
{
  "mcpServers": {
    "sociallinks": {
      "url": "https://sociallinks.dev/mcp",
      "headers": {
        "Authorization": "Bearer sl_your_key"
      }
    }
  }
}
```

### VS Code (.vscode/mcp.json)

```
{
  "servers": {
    "sociallinks": {
      "type": "http",
      "url": "https://sociallinks.dev/mcp",
      "headers": {
        "Authorization": "Bearer sl_your_key"
      }
    }
  }
}
```

### Windsurf (~/.codeium/windsurf/mcp_config.json)

```
{
  "mcpServers": {
    "sociallinks": {
      "serverUrl": "https://sociallinks.dev/mcp",
      "headers": {
        "Authorization": "Bearer sl_your_key"
      }
    }
  }
}
```

### Gemini CLI (~/.gemini/settings.json)

```
{
  "mcpServers": {
    "sociallinks": {
      "httpUrl": "https://sociallinks.dev/mcp",
      "headers": {
        "Authorization": "Bearer sl_your_key"
      }
    }
  }
}
```

## Errors
- 400: Not a profile URL (posts, reels, videos and bare @handles are refused), or no body.
- 401 invalid_api_key: The key is unknown or revoked.
- 401 login_required: No key was sent.
- 402 out_of_credits: No credits left. Nothing was charged; buy a pack and retry.
- 404: No such batch on this account.
- 409: The batch has already finished.
- 429: Too many fresh lookups. Wait Retry-After seconds, or send the list to /batches.
- 502: The lookup broke on our side. You weren't charged; try again.

## Rate limits
- Fresh lookups per key: 5 per minute
- Creators already looked up: No limit; served instantly
- Profiles per batch: 500
- Active API keys per account: 10