Ask social data in plain English
POST /v1/ask takes a natural-language question, picks the matching Social Fetch operation across 17 platforms (137 marketplace ops), runs the lookup, and returns the same structured JSON a typed route would. Routing costs 0 credits; only the nested lookup bills.
What Ask does
You send a question like "How many TikTok followers does MrBeast have?" We parse intent, extract the handle or URL, map it to a documented operation, and execute that lookup. The response includes `data.routedOperation` (which path we chose) plus the nested lookup payload — same envelope as REST and MCP.
Ask is a System-tag route: a router over the marketplace catalog, not a platform hub of its own. Once you know the operation, call the typed GET path in production. Keep Ask for exploration, agent prototypes, and Slack-style one-offs.
Ask vs typed endpoints
Ask when you do not know the route yet
Agents and humans can ask in English without grepping OpenAPI first. The response tells you which operation ran so you can pin it next time.
Typed paths when the workflow is fixed
Cron jobs, billing pipelines, and stable tool manifests should call the explicit GET. Same schema, no routing step, fewer surprises.
One shot, not a chat
Each POST is one routed lookup. No thread, no memory, no multi-turn agent loop on our side. Compare TikTok and YouTube for the same creator with two calls.
Credits
Routing on POST /v1/ask costs 0 credits. The nested marketplace lookup bills at that endpoint's normal rate (usually 1 credit on a completed standard lookup). Infrastructure failures are not charged. A completed `not_found` or `private` result is still a billed lookup — same rules as calling the typed path directly.
How routing works
- 1
Parse intent
Match platform and resource type — profile, channel, search, post, transcript, and similar.
- 2
Extract params
Pull handles, URLs, and search terms from the question so you do not need the path template up front.
- 3
Run the lookup
Dispatch the typed operation and return `data.routedOperation` plus the live nested response.
Try it and wire it up
- API docs
OpenAPI reference for POST /v1/ask — params, examples, response shape.
- Free Ask tool
Free browser demo. No signup for simple profile and search lookups.
- MCP
Hosted MCP with OAuth — Cursor, Claude, VS Code. Product overview and install.
- Playground
Run Ask with your API key in the Social Fetch app.
Example request
FAQ
Is Ask a chatbot?
No. One question, one routed lookup, structured JSON back. No thread or memory on our side.
How much does POST /v1/ask cost?
Routing costs 0 credits. The nested lookup bills at that endpoint's normal credit rate. Check meta.creditsCharged on the response.
When should I use typed endpoints instead?
Once the workflow is stable. Read data.routedOperation from an Ask response, then call that GET path directly for cron jobs, production agents, and anything with a fixed schema contract.
Why name the platform in the question?
Creators like MrBeast exist on multiple networks. Naming TikTok, YouTube, or Instagram helps the router pick the right operation on the first try.
How is this different from GET /v1/web/ask?
POST /v1/ask routes social platform lookups across the marketplace catalog. GET /v1/web/ask answers a question about one public URL's page content.
Can agents use Ask via MCP?
Yes. The hosted MCP tool nl_ask_post mirrors POST /v1/ask. Use it to explore, then pin typed MCP tools once you know the route. Pair with /llms.txt so agents stop inventing endpoints.
Does Ask cover all 17 platforms?
Ask routes over the same marketplace catalog as the rest of the API — 17 platforms and 137 operations. Coverage matches what typed routes support; Ask does not invent platforms outside that catalog.
Get an API key and start asking
100 free credits, no card. Prototype with Ask, then pin typed routes when the operation is known.