# Vercel AI SDK (/docs/frameworks/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](https://ai-sdk.dev/docs) for current versions. ```bash title="Terminal" npm install ai @ai-sdk/anthropic zod export SOCIALCRAWL_API_KEY=sc_your_key_here ``` ## Connect 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. ```typescript title="TypeScript" // 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) { 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](/platforms) or [`llms.txt`](/docs/ai-agents.md) 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](/docs/skills-and-mcp.md). ## Read a profile and its posts Quote the call, then let the model run it with a step limit. ```typescript title="TypeScript" 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 **TypeScript rejects `parameters` or `maxTokens`** Those are the v5 names. AI SDK v6 uses `inputSchema` and `maxOutputTokens`, as above. **The model calls the tool but never answers** `stopWhen` is missing or set to one step, so generation ends on the tool result. `stepCountIs(5)` leaves room to answer. **The model reasons about an error as if it were data** `execute` is returning the raw envelope. Check `json.success` and return a short directive, as `sc` does. See [Errors](/docs/errors.md). **A call returns 429 or 503** Honour the `Retry-After` header and back off. See [Rate limits](/docs/rate-limits.md). **The agent guesses endpoints that do not exist** Give it the catalogue in [`/llms-full.txt`](/llms-full.txt), or use an MCP client, which validates each call before it spends. ## How do I control credit spend? `/v1/utility/estimate` tells you what a call will hold before you make it, and [Endpoint pricing](/docs/endpoint-pricing.md) 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](/docs/credits.md). 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](/docs/errors.md) and [Credits](/docs/credits.md). ## 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)](/docs/streaming.md) for which endpoints stream. ## Resources - [LangChain](/docs/frameworks/langchain.md): The same pattern in that framework. - [Skills and MCP](/docs/skills-and-mcp.md): Skip the wrapper with a one-line MCP install. - [Streaming (SSE)](/docs/streaming.md): Which endpoints stream and what the frames look like. - [Batch endpoints](/docs/batch.md): Replace a loop of tool calls with one request.