Using an AI agent
Paste one prompt into Claude, ChatGPT, Cursor, or any coding agent and let it set up SocialCrawl and make the first calls for you
You do not have to read the rest of the docs. Copy the prompt below into your agent, or install the MCP server, and the agent reads the free catalogue, verifies your key, and makes the first calls for you.
Copy the prompt
Set up the SocialCrawl API (https://www.socialcrawl.dev) in this project and make a first successful call.
Facts you can rely on:
- Base URL: https://www.socialcrawl.dev/v1
- Auth: send the header x-api-key: YOUR_API_KEY on every request. Never put the key in a URL or commit it.
- Every response is one JSON envelope: success, platform, endpoint, data, credits_used, credits_remaining, request_id, cached. List responses add pagination { next_cursor, has_more }.
- Most calls cost 1 credit. Cache hits cost 0. Failed calls and empty results are refunded. New accounts start with 100 credits.
Before writing any call, read the free catalogue instead of guessing paths or parameters (0 credits each):
GET https://www.socialcrawl.dev/v1/utility/quickstart
GET https://www.socialcrawl.dev/v1/utility/endpoints?search=<topic>
GET https://www.socialcrawl.dev/v1/utility/endpoint?id=<platform/resource>
Then, in order:
1. Verify the key with GET https://www.socialcrawl.dev/v1/credits/balance and print the balance.
2. Call GET https://www.socialcrawl.dev/v1/tiktok/profile?handle=charlidamelio and print data.author.followers and credits_used.
3. Change only the path to read the same handle on instagram/profile, youtube/channel, and twitter/profile. Print one line per platform.
4. Pick one list endpoint from the catalogue and page through it by sending pagination.next_cursor back as ?cursor= until has_more is false.
Branch on error.type, never on the message text. Only RATE_LIMITED, CONCURRENCY_LIMIT, UPSTREAM_ERROR, SERVICE_UNAVAILABLE, and INTERNAL_ERROR are worth a retry.
References (read these, do not summarise from memory):
https://www.socialcrawl.dev/docs/quickstart.md
https://www.socialcrawl.dev/llms.txtReplace YOUR_API_KEY before you send it, or sign in and it is filled in for you.
The prompt tells the agent the three things it must not guess (the base URL, the header, the response shape), makes it read the free catalogue before it writes a call, and gives it four concrete tasks that end with the same handle read on four platforms. If you are signed in, your key is already in it.
Or connect the agent directly
An MCP server and an Agent Skill give the agent the same catalogue as tools, so it never has to type a URL by hand.
# Hosted server, nothing to install
claude mcp add --transport http socialcrawl https://mcp.socialcrawl.dev/mcp \
--header "Authorization: Bearer YOUR_API_KEY"
# Or the local package
claude mcp add --scope user socialcrawl -e SOCIALCRAWL_API_KEY=YOUR_API_KEY -- npx -y socialcrawl-mcpAdd this to the client's MCP configuration. Cursor reads .cursor/mcp.json; Claude Desktop, VS Code, and Windsurf use the same shape.
{
"mcpServers": {
"socialcrawl": {
"command": "npx",
"args": ["-y", "socialcrawl-mcp"],
"env": { "SOCIALCRAWL_API_KEY": "YOUR_API_KEY" }
}
}
}npx skills add socialcrawl/skillsThe skill teaches the agent the catalogue-first workflow and the response shape. It works in any agent that reads SKILL.md files.
Restart the agent after setup so it discovers the new tools. The full client list, with per-client screenshots, is in Skills and MCP.
What the agent will do first
Every good agent run on SocialCrawl starts the same way, and you can ask for it by name:
GET /v1/credits/balanceto prove the key works. Costs 0.GET /v1/utility/endpoints?search=<what you need>to find the endpoint. Costs 0.GET /v1/utility/endpoint?id=<platform/resource>for its parameters, cost, and paging rule. Costs 0.- One real call, then the same call on a second platform by changing one path segment.
curl "https://www.socialcrawl.dev/v1/utility/endpoints?search=comments" \
-H "x-api-key: YOUR_API_KEY"Give the agent the docs
Every page here is plain Markdown when you append .md to its URL, and the whole API is indexed in one file:
- /llms.txt: the short index.
- /llms-full.txt: every endpoint with parameters, costs, and errors.
/v1/utility/llms?platform=tiktok: one platform's context as an API call.- /v1/openapi.json: the OpenAPI 3.1 spec.
Prefer to do it yourself?
The step-by-step quickstart walks through the same first calls by hand: your key, the runnable first call, the response shape, and a four-platform script.