AI Agent Integration
Using SocialCrawl with AI agents and LLMs
AI Agent Integration
SocialCrawl is designed to be consumed by AI agents. When an endpoint supports a computed field and the required source inputs are present, its response includes that optional field for downstream reasoning. Depending on the endpoint, these fields can include engagement_rate, language, content_category, and estimated_reach. The entire 400-endpoint catalogue is published as machine-readable llms.txt and OpenAPI files.
If you're using Claude Code, Cursor, Windsurf, Claude Desktop, or any other MCP-compatible client, install the Skills or MCP package for a one-line setup — your agent gets local schema validation, zero-credit discovery tools, and direct access to every bundled endpoint without plumbing any HTTP yourself. For a full walkthrough of the tools and one-line install commands, see the MCP server for social media data page.
How do AI agents discover SocialCrawl?
We provide machine-readable documentation at:
- /llms.txt — Compact overview of the API
- /llms-full.txt — Complete self-contained reference, including the
GET /v1/credits/balancemeta endpoint, idempotency semantics,oneOfparameter constraints, and all error codes - /llms.json — Machine-readable catalog (per-platform endpoint counts, auth, credit tiers, response envelope), generated from the live registry
- /agents.txt — AI agent access file: capabilities, quick start, and crawl guidance in one place
Point your AI agent at /llms-full.txt for everything it needs to use the API.
How do I read a docs page as Markdown?
Append .md to any docs URL (the DataFast / Fumadocs convention):
/docs→/docs.md/docs/quickstart→/docs/quickstart.md/docs/api-reference→/docs/api-reference.md
You can also send Accept: text/markdown on the HTML URL. Every docs page has an "AI agent or LLM? Read this page as markdown" link that points at the same twin. Twins are text/plain, X-Robots-Tag: noindex, and listed in /sitemaps/llm.xml.
How can agents use the OpenAPI specification?
The full OpenAPI 3.1 specification is available at:
- /v1/openapi.json — JSON format
- /v1/openapi.yaml — YAML format
What per-platform documentation is available?
Fetch only the endpoints you need — one file per platform, one per active platform on the API:
Each file contains only that platform's endpoints with parameters, descriptions, and curl examples. One file exists per active platform, and /llms.txt links the current list — treat that as the source of truth if this table ever trails a new platform launch.
How do I integrate SocialCrawl with my AI agent?
const apiKey = process.env.SOCIALCRAWL_API_KEY;
if (!apiKey) throw new Error("Set SOCIALCRAWL_API_KEY");
const response = await fetch(
"https://www.socialcrawl.dev/v1/tiktok/profile?handle=charlidamelio",
{ headers: { "x-api-key": apiKey } },
);
const json = await response.json();
if (!json.success) {
// Machine-readable failure: branch on error.type, follow error.doc_url.
throw new Error(`${json.error.type}: ${json.error.message}`);
}
// json.data is structured and ready for AI reasoningNever hand a raw { "success": false, ... } envelope back to a model as if it were data — it will reason around the error instead of retrying or reporting it. Branch on success first, use error.type to decide what to do, and honour the Retry-After header on a 429 or 503. The full list is on the Errors page.