# LangChain (/docs/frameworks/langchain) Give a LangChain agent social media data, with the price shown before it spends. SocialCrawl does not ship a LangChain package and does not need one. The API is a single authenticated GET request, so you wrap it in a `tool()` in about 30 lines and your agent reaches 95 platforms through that one tool. Documented endpoint caches apply. ## Setup You need Node.js with a runner such as `tsx`, a key for the model you bind the tool to, and a SocialCrawl key from the dashboard under API Keys. New accounts start with free credits. See the [LangChain docs](https://docs.langchain.com/oss/javascript) for current versions. ```bash title="Terminal" npm install langchain @langchain/anthropic zod export SOCIALCRAWL_API_KEY=sc_your_key_here ``` ## Connect Give the tool a zod schema with a `platform`, a `resource` and the endpoint's `params`, and call the REST API inside it with your key in `x-api-key`. A second tool quotes a call for free. `createAgent` runs the tool loop for you. ```typescript title="TypeScript" // socialcrawl-langchain.ts // Run with: SOCIALCRAWL_API_KEY=sc_... ANTHROPIC_API_KEY=... npx tsx socialcrawl-langchain.ts import { createAgent, tool } from "langchain"; import * as 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( // Return a string so the model can read it back as a tool message. async ({ platform, resource, params }) => JSON.stringify(await sc(`/v1/${platform}/${resource}`, params)), { name: "socialcrawl", 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 estimate_cost first.", schema: 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, }), }, ); const estimateCost = tool( async ({ endpoint, params }) => JSON.stringify(await sc("/v1/utility/estimate", { id: endpoint, ...params })), { name: "estimate_cost", description: "Quote the credits a SocialCrawl call will hold. Free. Call it before socialcrawl and tell the user the answer.", schema: z.object({ endpoint: z.string().describe("platform/resource, e.g. 'tiktok/profile'"), params: paramsSchema, }), }, ); ``` ### 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 what 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 bind both tools to a model and run. ```typescript title="TypeScript" console.log(await sc("/v1/utility/estimate", { id: "tiktok/profile", handle: "charlidamelio" })); const agent = createAgent({ model: "claude-sonnet-5", tools: [socialcrawl, estimateCost], }); const result = await agent.invoke({ messages: [ { role: "user", content: "Quote, then read how many followers @charlidamelio has on TikTok.", }, ], }); console.log(result.messages.at(-1)?.content); ``` `createAgent` from the `langchain` package is the LangChain v1 standard. It replaced `createReactAgent` and runs the model-and-tool loop itself, so a query that needs two rounds of tool calls still works. Swap in any model string LangChain resolves. To drive the loop by hand, `new ChatAnthropic({ model }).bindTools([socialcrawl])` still works: iterate `response.tool_calls`, push a `ToolMessage` per call, and invoke again until the model stops asking for tools. ### Troubleshooting **The model answers without calling the tool** Its description is too vague for the router. Keep the platform and resource examples in `description`, and name a platform in the prompt ("on TikTok") while you tune it. **The agent stops after the tool call instead of answering** The loop ran out of steps. A hand-rolled `bindTools` loop must keep invoking the model until `response.tool_calls` is empty. **The model reasons about an error as if it were data** The tool 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 keep the agent from spending too many credits? `/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. Read `credits_remaining` after each call to track spend, and see [Credits](/docs/credits.md). Call `estimate_cost` before any paid call and show the answer to the person who owns the key. 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). ## Resources - [Vercel AI SDK](/docs/frameworks/vercel-ai-sdk.md): The same pattern in that framework. - [Skills and MCP](/docs/skills-and-mcp.md): Skip the wrapper with a one-line MCP install. - [Batch endpoints](/docs/batch.md): Replace a loop of tool calls with one request. - [Authentication](/docs/authentication.md): Keys, headers, and what a 401 means.