> **For coding agents and LLMs:** This is one Social Fetch marketing page (markdown export). For API orientation start with [`/llms.txt`](https://www.socialfetch.dev/llms.txt); for auth and crawl rules use [`/agents.txt`](https://www.socialfetch.dev/agents.txt); for every operation use [`/llms-endpoints.txt`](https://www.socialfetch.dev/llms-endpoints.txt). ## This page - **On-site (HTML):** - **Markdown (.mdx) URL:** --- # 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. ## Related - [Ask product page](https://www.socialfetch.dev/ask) - [Ask free tool](https://www.socialfetch.dev/tools/ask) - [API docs](https://www.socialfetch.dev/docs/api) - [MCP for social data](https://www.socialfetch.dev/glossary/mcp-for-social-data) - [Platforms](https://www.socialfetch.dev/platforms) - [Unified schema](https://www.socialfetch.dev/unified-schema) - [requestId](https://www.socialfetch.dev/glossary/request-id)