Ask social data questions in plain English

The old API deal: here's the catalog, here are the params, good luck. Fine when humans were the only integrators.

Less fine now. Your teammate asks in Slack for MrBeast's TikTok followers. Your agent has a tool slot and a user question, not an afternoon to grep OpenAPI specs. Sometimes you want to try a lookup before you pick a path in code. The bottleneck is usually finding the right endpoint, not the data itself.

We shipped POST /v1/ask: plain English on the way in, the same structured JSON our typed endpoints return on the way out.

typescript

No path template. No up-front debate about handle vs channelId. You ask. We route, run the lookup, and return the same structured data the typed endpoint would have returned.

Why agents benefit from a natural-language route

Tool use works when the model can ask in plain language and get a reliable result. It works less well when every run starts with locating operationId tiktok.profile.get in the spec. A natural-language endpoint cuts token overhead and routing mistakes on exploratory calls.

It does not replace typed routes, stable schemas, or boring envelopes. We still publish full reference docs. Ask in English when you are exploring. Pin the typed endpoint when you are shipping a cron job.

How the natural language API works

When you send "get the Instagram profile for @instagram," the intent router picks the platform (TikTok, YouTube, Instagram, and the rest) and the data type you want: profile, video, search, comments. It extracts handles, URLs, and search terms from the text, so you do not need our path templates up front. Then we run the underlying typed endpoint and return the same JSON you would get from calling that route directly.

Each call is one shot. No thread, no memory, no back-and-forth on our side. You get the lookup payload plus data.routedOperation, which records which path we chose. That field is useful for debugging, for agents, and for discovering the typed route to use in production.

Try the Ask demo

We put a free browser demo on the site for exactly this: you have a question, you want to see if the router gets it, and you do not want to sign up first.

Open /tools/ask, type a question, submit. You will see the routed operation and the live response — the production Ask route, without signing up first.

The demo is capped to simple one-credit lookups so the page stays fair. When you need volume, grab a key and call Ask (or the typed route it returns) from your backend.

Questions we typed while testing:

How many TikTok followers does MrBeast have?
How many YouTube subscribers does MrBeast have?
Get the Instagram profile for @instagram

If you already have an API key, the playground under Ask does the same thing with your credentials.

When to use Ask vs typed routes

Natural language does not replace your integration layer. For cron jobs, billing pipelines, and anything with a fixed schema contract, call the typed route.

What Ask gives you is intent in, JSON out, without a documentation detour first. Agents enriching user context on the fly can call ask instead of injecting a full OpenAPI spec into every run. Internal Slack bots can answer "how many followers does X have on TikTok?" without a custom command per platform. When you are still exploring what data exists across networks, you can poke at a few questions before you wire specific routes.

A few things to expect:

Vague questions ("how many followers does MrBeast have?") may fail or pick the wrong network. Name the platform.
One question, one lookup. Comparing TikTok and YouTube for the same creator is two calls.
Off-topic questions get rejected before a lookup runs. You are not charged for those.
Routing on POST /v1/ask costs 0 credits. The nested lookup bills at that endpoint's normal rate on a completed lookup. Infrastructure failures are not charged. A completed not_found or private result still bills, same as calling the typed path directly. Trust meta.creditsCharged. See Pricing.