Use SocialCrawl with the Vercel AI SDK
Give a Vercel AI SDK agent social media data, with the price shown before it spends.
SocialCrawl has no dedicated AI SDK provider and does not need one. The API is a single authenticated GET request, so you wrap it in a tool() and hand it to generateText, and one tool reaches 95 platforms. Documented endpoint caches apply.
Setup
You need Node.js with a runner such as tsx, a key for the model you pass to generateText, and a SocialCrawl key from the dashboard under API Keys. New accounts start with free credits. See the AI SDK docs for current versions.
npm install ai @ai-sdk/anthropic zod
export SOCIALCRAWL_API_KEY=sc_your_key_hereConnect
Give the main tool a zod inputSchema with a platform, a resource and the endpoint's params, and call the REST API inside execute with your key in x-api-key. A second tool quotes a call for free, so the agent shows the price first.
// socialcrawl-ai-sdk.ts
// Run with: SOCIALCRAWL_API_KEY=sc_... ANTHROPIC_API_KEY=... npx tsx socialcrawl-ai-sdk.ts
import { generateText, tool, stepCountIs } from "ai";
import { anthropic } from "@ai-sdk/anthropic";
import { z } from "zod";
const API_KEY = process.env.SOCIALCRAWL_API_KEY;
if (!API_KEY) throw new Error("Set SOCIALCRAWL_API_KEY");
// One GET against the REST API. Return the data, or a short directive the model can act on.
export async function sc(path: string, params: Record<string, string | number>) {
const url = new URL(`https://www.socialcrawl.dev${path}`);
for (const [key, value] of Object.entries(params ?? {})) {
url.searchParams.set(key, String(value));
}
const res = await fetch(url, { headers: { "x-api-key": API_KEY } });
const json = await res.json();
if (!json.success) {
return `SocialCrawl error ${json.error.type}: ${json.error.message}. See ${json.error.doc_url}`;
}
return json.data;
}
const paramsSchema = z
.record(z.string(), z.union([z.string(), z.number()]))
.describe("Query parameters for the endpoint");
const socialcrawl = tool({
description:
"Fetch current public social media, commerce, and review data from SocialCrawl; documented endpoint caches apply. " +
"Set `platform` (e.g. 'tiktok'), `resource` (e.g. 'profile'), and `params` " +
"(the endpoint's query fields, e.g. { handle: 'charlidamelio' }). Paid, so call estimateCost first.",
inputSchema: z.object({
platform: z.string().describe("Platform slug, e.g. 'tiktok' or 'youtube'"),
resource: z.string().describe("Endpoint resource, e.g. 'profile' or 'search'"),
params: paramsSchema,
}),
execute: ({ platform, resource, params }) => sc(`/v1/${platform}/${resource}`, params),
});
const estimateCost = tool({
description:
"Quote the credits a SocialCrawl call will hold. Free. Call it before socialcrawl and tell the user the answer.",
inputSchema: z.object({
endpoint: z.string().describe("platform/resource, e.g. 'tiktok/profile'"),
params: paramsSchema,
}),
execute: ({ endpoint, params }) => sc("/v1/utility/estimate", { id: endpoint, ...params }),
});What can the tool call?
Every endpoint is a GET at /v1/{platform}/{resource} with query parameters and one x-api-key header, and returns the same JSON envelope. One tool therefore reaches all 801 endpoints.
| To let the agent do this | Pass |
|---|---|
| Read one profile, post, or listing | platform: "tiktok", resource: "profile", params: { handle: ... } |
| Search one platform | platform: "youtube", resource: "search", params: { query: ... } |
| Search many sources at once | platform: "search", resource: "everywhere" |
| Check the balance before it spends | platform: "credits", resource: "balance" |
Point the model at the platform directory or llms.txt so it knows which values to pass. To skip the wrapper, an MCP client gets the same access with one command and checks each call before it costs a credit. See Skills and MCP.
Read a profile and its posts
Quote the call, then let the model run it with a step limit.
console.log(await sc("/v1/utility/estimate", { id: "tiktok/profile", handle: "charlidamelio" }));
const { text } = await generateText({
model: anthropic("claude-sonnet-5"),
tools: { socialcrawl, estimateCost },
// Let the model quote, call the tool, then answer with the result.
stopWhen: stepCountIs(5),
maxOutputTokens: 1024,
prompt: "Quote, then read how many followers @charlidamelio has on TikTok.",
});
console.log(text);The tool uses inputSchema (the AI SDK v6 field, not parameters) and the call uses maxOutputTokens (not maxTokens). stopWhen: stepCountIs(5) allows up to five steps, so a question that needs two lookups still resolves. Newer releases name it isStepCount and keep stepCountIs as an alias. Swap in any provider model; the tools do not change.
Troubleshooting
How do I control credit spend?
/v1/utility/estimate tells you what a call will hold before you make it, and Endpoint pricing lists every price. Cache hits cost nothing, and empty results and upstream errors are refunded. Each envelope carries credits_remaining, so you can show spend or stop on a budget. See Credits.
Call estimate_cost before any paid call and show the answer to the person who owns the key. Keep stepCountIs small, and add max_credits to list calls so a walk stops where you set it. A 402 means the account is out of credits. Tell the user it is an offer to top up and stop, because a retry cannot succeed. See Errors and Credits.
Can I stream results into the UI?
Yes, for the endpoints that support it. search/everywhere, search/news and several Prism composites answer with Server-Sent Events when you send Accept: text/event-stream, so you can render partial results while slow sources still run. That is a plain SSE stream you read yourself, not the AI SDK's own streamText transport. See Streaming (SSE) for which endpoints stream.
