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
Set up your agent
One prompt that connects your agent to SocialCrawl and makes its first call.
Templates
Tested programs an agent can read and run, also listed by GET /v1/utility/recipes.
Run your first request
This request asks the planner which calls a job needs. It costs nothing and runs nothing.
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"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"])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
- Connect the agent with the agent quickstart, or register the MCP server with your client.
- Plan the job: the agent asks
socialcrawl_findorGET /v1/utility/planfor the calls and their prices. - Run the calls with a
max_creditscap 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.
