SocialCrawl

Use SocialCrawl with 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 for current versions.

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
// 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<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(
  // 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 thisPass
Read one profile, post, or listingplatform: "tiktok", resource: "profile", params: { handle: ... }
Search one platformplatform: "youtube", resource: "search", params: { query: ... }
Search many sources at onceplatform: "search", resource: "everywhere"
Check the balance before it spendsplatform: "credits", resource: "balance"

Point the model at the platform directory or llms.txt 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.

Read a profile and its posts

Quote the call, then bind both tools to a model and run.

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

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 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.

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 and Credits.

Resources

On this page