What is the Ask natural-language API?
Ask is Social Fetch's natural-language router: POST /v1/ask (or nl_ask_post over MCP) with a question like "How many TikTok followers does MrBeast have?" We map it to a documented operation and return the same structured JSON a typed route would, plus which operation we chose.
What Ask actually does
Ask is a routing layer, not a chat interface. Send { "query": "..." } to POST /v1/ask; Social Fetch picks a typed marketplace operation, runs it, and returns that operation's normal response. It saves you from knowing the exact endpoint up front — it doesn't replace the typed API.
The same logic is available as nl_ask_post over MCP for agents that connect via OAuth rather than REST.
A concrete example
"How many TikTok followers does MrBeast have?" returns the TikTok profile payload plus a field identifying which operation Ask picked, with meta.requestId, creditsCharged, and version as on a direct call.
Calling the typed TikTok profile endpoint directly with the handle returns the same data shape — Ask just resolved endpoint and parameters from plain English.
Billing: routing is free, the lookup isn't
Interpreting the question and choosing an operation costs 0 credits. The nested lookup bills at the same rate as calling that typed endpoint directly.
Exploratory questions through Ask don't add a routing charge — the meter starts when a real lookup runs.
How to use it without re-routing every call
Ask fits exploration, prototyping, and agent workflows where the question isn't known ahead of time. Read the routed-operation field to see which endpoint answered.
For repeat or scheduled jobs, call the typed route (or matching MCP tool) directly once you know which operation fits — skip routing overhead and avoid phrasing-dependent inference.
Ask requires authentication: sfk_… via x-api-key on REST, or OAuth for hosted MCP at https://api.socialfetch.dev/mcp. Not available anonymously.
How this compares to routing it yourself
Without Ask, you'd maintain a classifier mapping questions to endpoints — kept in sync every time Social Fetch adds operations. Ask exposes that routing as a single versioned endpoint.
Unlike LLM-synthesized answers, Ask always resolves to a documented typed operation with the standard { data, meta } envelope. If the question doesn't map cleanly, you get a typed error, not a guess.
What Ask is not
Not a chatbot — no conversational memory; each POST /v1/ask is independent.
Not a substitute for learning the typed API in production. Once you know the endpoint, call it directly — faster and more predictable.
Not free for underlying data. Routing costs nothing; the lookup bills like a direct call — see /docs/credits.
FAQ
How does the Ask endpoint work?
POST /v1/ask (or nl_ask_post) with { "query": "..." }. Social Fetch matches a documented operation, runs it, and returns { data, meta } plus which operation was chosen.
Does natural-language routing cost credits?
No. Routing is 0 credits; only the nested lookup bills at the normal rate.
Do I need an API key to use Ask?
Yes — sfk_… via x-api-key for REST, or OAuth for hosted MCP. Not available anonymously.
Is Ask a chatbot?
No. It's a router into documented lookups — structured JSON, not generated prose.
Should production jobs call Ask directly?
Prefer the typed endpoint once you know it. Read data.routedOperation from Ask, then call that route for repeat work.
How does Ask relate to MCP tools?
MCP exposes each operation as a typed tool. Ask (nl_ask_post or POST /v1/ask) sits in front when an agent doesn't yet know which one. See /glossary/mcp-for-social-data.
What happens if Ask can't figure out which operation to call?
A typed error — not a guess. Ask returns data only when it matches a documented operation.
Can I use Ask without signing up?
Not the API route — it requires a key or OAuth. Try /tools/ask for manual one-off questions.