Vercel AI SDK
Use SocialScrape from the Vercel AI SDK with the @socialscrape/ai-sdk package, nine tools for profiles, posts, comments, transcripts and search.
@socialscrape/ai-sdk is the official Vercel AI SDK integration. It gives a model tools for the jobs agents do most (a profile, its posts, one post, the comments, a video transcript, a search), a tool that runs any other endpoint by id, and a credit check. It builds on the TypeScript SDK, so retries, timeouts and long transcription jobs are handled for you. It works with ai 6 and 7 and zod 4.
Install
npm install @socialscrape/ai-sdk ai zod
export SOCIALSCRAPE_API_KEY="YOUR_KEY"
Create a key in the dashboard; a new account starts with 100 free credits. Keep the key on the server: it is a secret, so it never goes in code that ships to a browser. The source is on GitHub and the package is on npm.
Give a model the tools
import { generateText, isStepCount } from 'ai';
import { socialscrapeTools } from '@socialscrape/ai-sdk';
const { text } = await generateText({
model: 'openai/gpt-5-mini',
prompt: 'What did NASA post on YouTube this week, and what are people saying in the comments?',
tools: socialscrapeTools(), // reads SOCIALSCRAPE_API_KEY
stopWhen: isStepCount(5),
});
console.log(text);
Any model that supports tool calling works. The platform is an argument the model fills in, for example { platform: "tiktok", handle: "nasa" }. For a post, its comments or a transcript the platform is read from the link.
Tools
| Tool | What it does | Credits |
|---|---|---|
getProfile | A profile, channel or artist: name, bio, links, verification and follower counts. | 1 |
getPosts | The latest posts or videos of a profile, channel or page, one page per call. | 1 per page |
getPost | One post, video, tweet, pin or clip from its URL. | 1 |
getComments | The comments on a post or video, one page per call. | 1 per page |
getTranscript | The transcript of a video from its URL. See AI transcription for what happens when a video has no captions. | 1 with captions; AI transcription 1 up to 2 minutes, then 5 per started minute of the whole video |
search | Keyword search on one platform, one page per call. | 1 per page |
listEndpoints | Every endpoint id with its parameters and price. It makes no request. | Free |
callEndpoint | Runs any endpoint in the API reference by its id, with its parameters by name. | Most 1; see the endpoint |
getCredits | The credit balance of the account. | Free |
Tools that list things return a cursor and has_more inside data; the model passes the cursor back for the next page, as described in pagination. A request that fails is free, and a cached answer costs 0 credits; see credits and caching.
To reach an endpoint that has no tool of its own, the model looks it up and calls it by id:
import { socialscrapeTools } from '@socialscrape/ai-sdk';
const tools = socialscrapeTools({ include: ['listEndpoints', 'callEndpoint'] });
// listEndpoints({ search: "ad library" })
// callEndpoint({ endpoint: "facebook.ad_library.search", params: { query: "running shoes" } })
Parameters are checked against the endpoint before the request is made, so a misspelt name is answered at once and costs nothing.
Use one tool directly
Each tool factory is exported on its own:
import { getProfile, getTranscript } from '@socialscrape/ai-sdk';
const tools = { getProfile: getProfile(), getTranscript: getTranscript() };
Every tool answers with an object that holds data (the object, or a list page with items, cursor and has_more), credits_charged and credits_remaining. The objects are the same models the REST API returns. Long answers are trimmed to fit a model: a list page loses items from its end and says so in truncated, and the cursor is kept.
Transcripts
getTranscript takes a video link on any supported platform. A short video, or one with captions, answers at once. A longer video with no captions needs allowLongTranscription: true, because AI transcription is billed per started minute of the whole video; without it the tool answers an error that names the cost, which is free. When transcription runs as a job, the tool waits for it to finish and answers with the transcript. The timed segments come back only when includeSegments is true; the full text always does.
Errors
A request the API refuses is free, as described in errors. A tool never throws: it returns the error as its answer, so the model can read it and try something else.
{
"ok": false,
"error": { "code": "not_found", "message": "...", "retryable": false, "request_id": "req_..." },
"billed": false,
"credits_charged": 0
}
error.code is the API's error code and retryable says whether the same request may succeed later. billed is always false. Arguments the model got wrong, such as a platform that does not fit the identifier it was given, answer invalid_params before any request is made. A missing key answers missing_api_key when a tool runs, so creating the tools never throws. A transcription that outlives the wait answers job_timeout with a job_id, and nothing is billed for that call.
Options
socialscrapeTools() and each tool factory take these:
| Option | What it does |
|---|---|
apiKey | The API key. Left out, it is read from SOCIALSCRAPE_API_KEY. |
baseUrl | API base URL override. |
include | Return only these tools: getProfile, getPosts, getPost, getComments, getTranscript, search, listEndpoints, callEndpoint, getCredits. |
maxAgeDays | Accept a cached result up to this many days old. A cached result costs 0 credits. |
trim | On by default: asks for the smaller response, without null fields and the extra object, which saves context. |
maxResponseChars | Most characters of JSON in one answer. Default 40000. |
maxTranscriptChars | Most characters of transcript text in one answer. Default 60000. |
client | A SocialScrape client from the TypeScript SDK that you configured yourself. |
clientOptions | Timeouts, retries or your own fetch for the client the tools make. |
Credits
A tool call is one API request and is charged like one: see credits. listEndpoints makes no request and getCredits is free.
Other agent frameworks
For Claude, ChatGPT, Cursor and other MCP clients, use the MCP server. For Python agents, see LangChain, CrewAI and Haystack.