A grounding API for AI agents: licensed search, cut to your token budget

Raw SERP JSON is the wrong shape for an agent

A search API that returns ten results, twenty snippets and a knowledge panel leaves you holding the hard part: deciding what survives the context window. Nearly every team writes the same two hundred lines — collapse near-duplicates, drop navigational noise, rerank against the question, count tokens, cut.

That code is where agents quietly go wrong. Trim by character count and a sentence ends mid-clause. Trim by result order and you keep three copies of the same press release. Skip the rerank and the model answers from position one because it was first, not because it was right.

• Two sites republishing one announcement are one fact, not two — and they cost you twice the tokens.
• A token budget is a wall you hit before the prompt is sent, not after the model truncates it.
• A block without a URL cannot be cited, which means the answer built on it cannot be audited.

What one call does

1. Step 1

   One licensed search

   You send a question and a token budget. We run a single search against licensed upstream providers — no anti-bot evasion, no residential proxy rotation, no CAPTCHA solving — and build candidate blocks from what it returns.

2. Step 2

   Dedupe and rerank before the cut

   Blocks are scored against your question, near-duplicates collapse into one, and the list is trimmed to your budget. What comes back is what fits, ordered by how well it answers rather than by where it ranked.

3. Step 3

   Citable, and signed

   Every block carries its title and url. The response carries a provenance receipt: the class of the source, whether any inference left the EU, and a SHA-256 of the exact body you were served — verifiable by someone who has no API key.

The call, in full

curl -X POST https://api.dataswap.io/v1/context \
  -H "Authorization: Bearer $DATASWAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "postgres logical replication limits",
    "token_budget": 4000,
    "depth": 10
  }'

{
  "blocks": [
    {
      "title": "Restrictions of logical replication",
      "url": "https://www.postgresql.org/docs/current/logical-replication-restrictions.html",
      "text": "Logical replication does not replicate schema changes, sequence data ...",
      "score": 0.94,
      "tokens": 118
    }
  ],
  "total_tokens": 3871,
  "credits_used": 3,
  "request_id": "req_8f3c9a12",
  "provenance": { "source_class": "mixed", "inference": "eu-only", "payload_sha256": "..." }
}

The calls, and what they cost

The quoted price is also the floor. Because the size of a pack varies, the call holds a declared ceiling and settles on what actually ran; the unused part is returned to your balance. Read GET /v1/pricing instead of hard-coding a table — it reports the quote, whether an operation is fixed or variable, and what the variation depends on.

1 credit = $0.002 on every plan. Full plans and prepaid packs are on the pricing section.

When this is the wrong tool

• You already have the URLs. /v1/context starts from a question, not from a list — POST /v1/extract/schema takes urls, and a general-purpose crawler is a different product that we do not sell.

• You need the full page body. Blocks are built from what the search itself returns; the deep mode adds the extra fields the search provides rather than downloading each article.

• You want bulk corpora for training. We sell per-call access to licensed data, not dumps.

• You need a market-specific index. A context pack answers a question rather than a locale, so the call takes no gl or hl — use POST /v1/search when the country matters.

Questions we get asked

Is POST /v1/context billed per token?

No. It is billed in credits per call, and 1 credit is $0.002 on every plan. The quoted price is 3 credits; because the size of a pack varies, the call reserves up to a declared ceiling and settles on the amount actually used, refunding the difference. Your token budget changes what you receive, never the unit you are billed in.

Where does the text in each block come from?

From licensed upstream providers. We do not scrape sources that forbid it, rotate residential proxies or solve CAPTCHAs. That is a contractual position rather than a setting, which is exactly why the receipt can carry a signed bot_evasion: false.

Do my queries reach a third-party model vendor?

No. Reranking and synthesis run on models we host ourselves, inside the EU, so no model vendor joins your sub-processor chain. Each response records inference: eu-only in its receipt, which your data protection officer can verify with POST /v1/provenance/verify without an API key.

Can an MCP client call it?

Yes. npx @dataswap.io/mcp exposes the tools to any MCP-capable agent using the same key, and every tool call is billed as the route it hits — there is no separate MCP price.

What happens when the search finds nothing usable?

You get blocks: [] and total_tokens: 0 rather than invented passages. The search that ran is still billed, because it ran; nothing else is.

How do I keep two identical calls from being billed twice?

Send an Idempotency-Key header. A replay with the same key and the same body returns the stored response instead of running and charging again.

Keep reading

• Fill a JSON Schema from the webWhen you want typed fields rather than passages.
• Dataswap vs TavilyThe closest comparison for agent grounding, including where Tavily is the better buy.
• AI tools referenceThe twelve analysis routes, with parameters and prices.
• BlogNotes on how this is built and measured.