Home / Documentazione API

Reference API

API di Social links

Un profilo creator in ingresso, tutti gli account in uscita. Invia un link a un profilo Instagram, TikTok, YouTube o X e ricevi gli account del creator sulle altre piattaforme, ognuno con un verdetto, un punteggio di affidabilità e le prove che lo sostengono.

URL di basehttps://sociallinks.dev/v1

Cosa puoi fare

Cerca un creatorUn link di profilo in ingresso, gli altri account del creator in uscita.POST /resolveCerca molti creatorMetti in coda fino a 500 profili; vengono elaborati in background.POST /batchesScarica un batch in CSVUna riga per profilo inviato, una colonna per piattaforma, più lo stato e i crediti addebitati.GET /batches/{id}/exportControlla il saldoCrediti rimasti sull'account della chiave.GET /balance

Specifica OpenAPIIl contratto completo, per generatori di codice e agenti IA.

Apri

Autenticazione

Crea una chiave in Dashboard → API e inviala con ogni richiesta come Authorization: Bearer sl_… (oppure x-api-key: sl_…). Le chiavi usano i crediti del tuo account. Una chiave viene mostrata una sola volta, alla creazione; se la revochi smette subito di funzionare.

Server MCP

Fai ricerche da Claude Code, Cursor, VS Code, Windsurf, Gemini CLI o qualsiasi client MCP. Aggiungi https://sociallinks.dev/mcp come server remoto (Streamable HTTP) e invia la chiave API nell’header Authorization. Gli strumenti costano esattamente come gli endpoint REST.

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

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

Strumenti

lookup_creator
Cerca un creator dall’URL di un profilo; addebitato solo se trova account.
check_balance
Crediti rimasti sull’account della chiave. Gratis.
start_batch
Mette in coda molti URL di profili da cercare in background.
get_batch
Avanzamento e righe di un batch.

Addebiti

1 credito per creator quando troviamo almeno un account oltre a quello che hai inviato. Le ricerche che non trovano nulla, e quelle che falliscono, sono gratuite. Cercare di nuovo un creator che il tuo account ha pagato negli ultimi 30 giorni è gratis. I crediti sono condivisi con il sito; vedi i prezzi.

Cerca un creator

POST/resolve

Invia l'URL di un profilo Instagram, TikTok, YouTube o X. Ricevi gli account del creator sulle altre piattaforme, ognuno con un verdetto, un punteggio di affidabilità netto e le prove che lo sostengono. Le nuove ricerche richiedono 10–40 secondi; i creator che abbiamo già tornano subito. 1 credito quando viene trovato almeno un account; se non si trova nulla è gratis. L'header X-Credits-Remaining riporta il tuo saldo.

Parametri

urlbody · stringobbligatorio
La pagina profilo di un creator. Post, reel, video e @handle da soli vengono rifiutati con 400.

Richiesta

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"}'

Risposta (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
}

Cerca un creator (GET)

GET/resolve

Identico a POST /resolve, per gli strumenti che possono inviare solo richieste GET.

Parametri

urlquery · stringobbligatorio
La pagina profilo di un creator, codificata come URL.

Richiesta

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

Risposta (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
}

Cerca molti creator

POST/batches

Ogni riga viene addebitata solo se trova account, e le righe che il tuo account ha pagato negli ultimi 30 giorni sono gratuite. Le righe che non sono link di profilo vengono saltate e mai addebitate. Controlla il batch, poi scarica il CSV.

Parametri

urlsbody · string[] | stringobbligatorio
Fino a 500 URL di profilo, come array o uno per riga.
namebody · string
Un'etichetta per il batch.

Richiesta

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"]}'

Risposta (201)

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

Controlla un batch

GET/batches/{id}

Controlla ogni pochi secondi finché lo stato non è "completed", "partial" o "failed". Ogni elemento ha il proprio stato e gli account trovati.

Parametri

idpath · uuidobbligatorio
L'id restituito da POST /batches.

Richiesta

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

Risposta (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"]
      }
    }
  ]
}

Scarica un batch in CSV

GET/batches/{id}/export

Pronto per un foglio di calcolo o un'importazione nel CRM.

Parametri

idpath · uuidobbligatorio
L'id del batch.

Richiesta

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

Risposta (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,

Elenca i tuoi batch

GET/batches

Comodo per riprendere da dove avevi lasciato.

Parametri

Nessuno.

Richiesta

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

Risposta (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"
    }
  ]
}

Ferma un batch

POST/batches/{id}/cancel

Le righe già in corso vengono completate. Restituisce 409 se il batch è già terminato.

Parametri

idpath · uuidobbligatorio
L'id del batch.

Richiesta

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

Risposta (200)

{ "ok": true }

Controlla il saldo

GET/balance

Gli stessi crediti usati dal sito. Acquista pacchetti su https://sociallinks.dev/pricing.

Parametri

Nessuno.

Richiesta

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

Risposta (200)

{ "credits": 742 }

Errori

Ogni errore ha la forma { "error": { "message", "code" } }. Il messaggio è leggibile; il codice serve quando vuoi gestire i casi separatamente.

Stato	Codice	Significato
400	`—`	Non è l'URL di un profilo (post, reel, video e @handle da soli vengono rifiutati), oppure manca il body.
401	`invalid_api_key`	La chiave è sconosciuta o revocata.
401	`login_required`	Non è stata inviata nessuna chiave.
402	`out_of_credits`	Crediti esauriti. Non è stato addebitato nulla; acquista un pacchetto e riprova.
404	`—`	Nessun batch del genere su questo account.
409	`—`	Il batch è già terminato.
429	`—`	Troppe nuove ricerche. Attendi i secondi indicati da Retry-After oppure invia l'elenco a /batches.
502	`—`	La ricerca non è riuscita per un problema nostro. Non ti è stato addebitato nulla; riprova.

Limiti di frequenza

Nuove ricerche per chiave	5 al minuto
Creator già cercati	Nessun limite; risposta immediata
Profili per batch	500
Chiavi API attive per account	10

Supporto

Domande o un bug? Scrivi a support@youtubetranscript.dev.