How should AI agents get social data?
Agents need the same public social data as any integration — profiles, posts, transcripts — but must branch programmatically on structured outcomes, discover real routes, and authenticate without leaking keys. Social Fetch supports that via lookupStatus, discovery files, OAuth MCP, and typed REST.
What makes an API agent-friendly
data.lookupStatus on HTTP 200 — branchable found/not_found/private instead of inferring from status code and prose.
Discoverability: /llms.txt, /agents.txt, /llms-endpoints.txt, /openapi.json, skill.md — read before guessing endpoints.
meta.creditsCharged and meta.requestId on every response for cost visibility and support.
How an agent connects, without leaking a key
Interactive agents (Claude, Cursor): hosted MCP at https://api.socialfetch.dev/mcp with OAuth — no sfk_ in mcp.json.
Production backends/CI: sfk_… in server env, REST or @socialfetch/sdk.
MCP tools: {platform}_{resource}_{action} — catalog covers 21 platforms, ~165 operations.
Discovery files and zero-cost routing
docs_search and docs_read on MCP are free. nl_ask_post / POST /v1/ask routes plain English at 0 credits; nested lookup bills normally.
Use routing once to find the operation, then call the typed tool/route for repeats.
A concrete agent workflow
nl_ask_post → routedOperation tiktok_profile_videos_list + first result. Check lookupStatus before using data. Switch to typed tool for batch handles. Log meta.requestId for wrong summaries.
Common mistakes agents make
Inventing endpoints — read /llms.txt or docs_search first.
Checking HTTP status only — 200 + not_found is completed, not missing data to act on.
Retrying not_found — bills again. Retry lookup_failed/503 only.
API key in shared MCP config — use OAuth for MCP, env vars for REST.
Boundaries: what agents shouldn't do with this
Public content only — no private accounts or login-gated data.
Production agents scraping HTML inherit every layout change. Documented endpoints keep metering, errors, and requestId in one place. 100 free credits on signup for end-to-end tests.
FAQ
How do I connect an AI agent to social media data?
MCP + OAuth for interactive clients. sfk_… key + REST/SDK for backend/batch.
Can Claude or Cursor call a social media API directly?
Yes via hosted MCP at https://api.socialfetch.dev/mcp — OAuth once, typed tools like tiktok_profile_get.
How does an agent avoid inventing endpoints that don't exist?
Read /llms.txt, /llms-endpoints.txt, /openapi.json, or call free docs_search/docs_read on MCP.
What is nl_ask_post and when should an agent use it?
Natural-language routing — 0 credits for routing. Use when the typed route is unknown; switch to typed tool for repeats.
Why check lookupStatus instead of just the HTTP status code?
200 with not_found/private is a completed billed answer — not transport failure or success with data.
Do agents get billed differently than human API calls?
No — same envelope and rules. docs_search, docs_read, and Ask routing are free.
Is it safe to put an API key in an MCP config file?
No — hosted MCP uses OAuth. Keys belong in server env for REST/SDK only.
Should a production agent scrape HTML instead of calling an API?
Generally no — HTML selectors break on layout changes. API keeps metering, errors, and requestId centralized.