For years the deal with APIs was simple: here is the catalog, here are the params, good luck.

That made sense when humans were the only integrators. You read the reference, you wired the route, you moved on.

It makes less sense now. Your teammate asks in Slack for MrBeast's TikTok followers. Your AI agent has a tool slot and a user question, not an afternoon to grep OpenAPI specs. Sometimes you just want to try a lookup before you commit to a path in code. The data was never the hard part — finding the right door was.

We have been wondering aloud: what if the API just understood the question?

A real HTTP call that takes plain English on the way in and returns the same structured JSON our typed endpoints always have on the way out.

We shipped exactly that: the Natural Language API for Social Fetch.

Here is the call:

// Just ask for the data you want. Make sure to include the platform :)
const result = await client.ask({
  query: "How many TikTok followers does MrBeast have?",
});

if (result.ok) {
  // Live TikTok profile JSON — we picked the route for you
  console.log(result.value.data.lookup);
}

No path template. No handle vs channelId debate up front. You ask; we route, run the lookup, and hand back the same structured data the typed endpoint would have returned.

Why AI agents need natural language APIs

LLMs are getting good at reading docs. They are also getting good at not needing to.

Tool use works best when the model can say what it wants in human language and get a reliable result back — not when every AI agent run starts with "first, locate operationId tiktok.profile.get in the spec." A natural language endpoint cuts token overhead and routing mistakes on exploratory calls.

Natural language at the boundary does not replace good API design. We still believe in typed routes, stable schemas, and boring envelopes. We are not throwing away the reference docs.

But there is room for a second front door: one question, one lookup, live data back. Ask in English when you are exploring. Pin the typed endpoint when you are shipping a predictable cron job.

That is the bet we made with POST /v1/ask.

How our natural language API works under the hood

When you send "get the Instagram profile for @instagram," our intent router figures out the platform (TikTok, YouTube, Instagram, and so on) and the data type you want: profile, video, search, comments. It extracts identifiers from the text too, so you do not need to know our path templates or whether the input is a handle, a channel ID, or a URL. Then we run the underlying typed endpoint and return the same structured 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 you would have gotten from the typed route, plus a clear record of which operation we chose. Useful for debugging, for agents, and for discovering the correct endpoint to use in production.

Test the social media API router live

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

Open /tools/ask, type a question, submit. You will see the routed lookup and the live response — the same production API our customers use, not a toy dataset.

The demo is capped to simple one-credit lookups so the page stays fair for everyone. When you are ready for volume, grab a key and call the same thing from your backend.

Some questions we have been typing ourselves 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 is the same idea with your credentials.

Best use cases for intent-driven API queries

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 it does give you is a useful second mode: 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. And when you are still exploring what data exists across networks, you can poke at a few questions before you commit to wiring specific routes.

A few things to expect:

• Vague questions ("how many followers does MrBeast have?") may fail or pick the wrong network. Be specific.
• One question, one lookup. Comparing TikTok and YouTube for the same creator is two calls, not one.
• Off-topic questions get rejected before a lookup runs. You are not charged for those.
• Routing is free in v1; you pay for the underlying lookup, same as always. See Pricing.

This is early, live, and we are watching how people use it. That is part of why we wanted a free tool and a blog post instead of burying it in a changelog line.

If you want the wires

Request shape, response fields, error codes, and billing: API reference for POST /v1/ask. The docs are where the spec lives; this post is the invitation.

We built Social Fetch to make social data boring and dependable. This is the slightly less boring front door — and we think that is worth showing off.

Go ask something.