SocialCrawl

AI agents and apps

Give an agent public social data through one key and the SocialCrawl MCP tools.

An agent on SocialCrawl needs one API key and a way to ask for calls. It plans the calls a job needs, prices them for free, then runs them under a cap you set. Every failure comes back with a type the agent can act on.

Start with a template

Run your first request

This request asks the planner which calls a job needs. It costs nothing and runs nothing.

cURL
curl -G "https://www.socialcrawl.dev/v1/utility/plan" \
  --data-urlencode "query=Combine @acme's TikTok profile with their recent videos and the comments on them" \
  -H "x-api-key: sc_your_key_here"
Python
import json
import urllib.parse
import urllib.request

params = urllib.parse.urlencode({
    "query": "Combine @acme's TikTok profile with their recent videos and the comments on them",
})
url = "https://www.socialcrawl.dev/v1/utility/plan"
req = urllib.request.Request(
    url + "?" + params,
    headers={"x-api-key": "sc_your_key_here"},
)
with urllib.request.urlopen(req) as res:
    plan = json.load(res)["data"]
for step in plan["steps"]:
    print(step["path"], step["credits"], step["run"])
TypeScript
const url = new URL("https://www.socialcrawl.dev/v1/utility/plan");
url.searchParams.set("query", "Combine @acme's TikTok profile with their recent videos and the comments on them");
const res = await fetch(url, {
  headers: { "x-api-key": "sc_your_key_here" },
});
const { data } = await res.json();
for (const step of data.steps) {
  console.log(step.path, step.credits, step.run);
}

The answer is a list of steps: the profile, then its videos, then the comments on each video. Each step carries its path, its price in credits, the values still missing and a ready cURL. A step marked blocked waits on a value from the step before it. Endpoint pricing lists the price of every call.

Before it runs a plan, the agent can price all of it with socialcrawl_estimate, which takes one call, a plan of several calls or a walk of a number of rows. To gather many rows, socialcrawl_collect walks the pages, supplies the cursors and drops duplicates. It stops at the rows you asked for, at the last page or at max_credits, and its result_id reads the stored result again for free. socialcrawl_account reads the balance and this session's spend for free, so the agent can tell you what a job cost.

How it works

  1. Connect the agent with the agent quickstart, or register the MCP server with your client.
  2. Plan the job: the agent asks socialcrawl_find or GET /v1/utility/plan for the calls and their prices.
  3. Run the calls with a max_credits cap and read the answer.

Why teams choose SocialCrawl

Discovery is free and needs no key. The three discovery tools of the MCP server, socialcrawl_find, socialcrawl_endpoint and socialcrawl_estimate, cost nothing.

The agent cannot pass your cap. socialcrawl_request refuses a call above max_credits, so no single call costs more than you allowed.

Errors say what to do next. Every failure carries an error.type to branch on and a doc_url that points at its entry in Error handling.

On this page