Home / API documentation

API reference

Social links API

One creator profile in, every account out. Send an Instagram, TikTok, YouTube or X profile link and get the creator's accounts on the other platforms, each with a verdict, a confidence score and the evidence behind it.

Base URLhttps://sociallinks.dev/v1

What you can do

Look up a creatorOne profile link in, the creator's other accounts out.POST /resolveLook up many creatorsQueue up to 500 profiles; they run in the background.POST /batchesDownload a batch as CSVOne row per profile sent, one column per platform, plus status and credits charged.GET /batches/{id}/exportCheck your balanceCredits left on the account behind the key.GET /balance

OpenAPI specificationThe full contract, for code generators and AI agents.

View

Authentication

Create a key under Dashboard → API and send it with every request as Authorization: Bearer sl_… (or x-api-key: sl_…). Keys spend your account's credits. A key is shown once when you create it; revoke it and it stops working at once.

MCP server

Run lookups from Claude Code, Cursor, VS Code, Windsurf, Gemini CLI or any MCP client. Add https://sociallinks.dev/mcp as a remote (Streamable HTTP) server and send your API key in the Authorization header. Tools are charged exactly like the REST endpoints.

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

Where it goes: Cursor ~/.cursor/mcp.json · VS Code .vscode/mcp.json · Windsurf ~/.codeium/windsurf/mcp_config.json · Gemini CLI ~/.gemini/settings.json

Tools

lookup_creator
Look up one creator from a profile URL; charged only when accounts are found.
check_balance
Credits left on the account behind the key. Free.
start_batch
Queue many profile URLs to look up in the background.
get_batch
Progress and rows for a batch.

Billing

1 credit per creator when we find at least one account beyond the one you sent. Lookups that find nothing, and failed lookups, are free. Looking up a creator your account paid for in the last 30 days is free. Credits are shared with the website; see pricing.

Look up a creator

POST/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

urlbody · stringrequired
A creator's profile page. Posts, reels, videos and bare @handles are refused with 400.

Request

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)

{
  "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/resolve

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

Parameters

urlquery · stringrequired
A creator's profile page, URL-encoded.

Request

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

Response (200)

{
  "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/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

urlsbody · string[] | stringrequired
Up to 500 profile URLs, as an array or one per line.
namebody · string
A label for the batch.

Request

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)

{
  "id": "6f1c2a4e-1b2c-4d3e-9f00-0a1b2c3d4e5f",
  "rows": 2,
  "invalid": 0,
  "duplicates": 0
}

Check a batch

GET/batches/{id}

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

Parameters

idpath · uuidrequired
The id POST /batches returned.

Request

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

Response (200)

{
  "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/batches/{id}/export

Ready for a spreadsheet or a CRM import.

Parameters

idpath · uuidrequired
The batch id.

Request

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

Response (200)

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/batches

Handy for picking up where you left off.

Parameters

None.

Request

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

Response (200)

{
  "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/batches/{id}/cancel

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

Parameters

idpath · uuidrequired
The batch id.

Request

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

Response (200)

{ "ok": true }

Check your balance

GET/balance

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

Parameters

None.

Request

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

Response (200)

{ "credits": 742 }

Errors

Every error is { "error": { "message", "code" } }. The message is readable; the code is there when you'd branch on it.

Status	Code	Meaning
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

Support

Questions or a bug? Email support@youtubetranscript.dev.