Live search

The gateway exposes live data and web search under /v1/search, with the same API key, rate limits, wallet, and spend caps as every other route. Behind it sits Tako: one call searches Tako’s curated knowledge graph (finance, macro, companies, sports, weather) and the live web, and returns knowledge cards — interactive, embeddable data visualizations backed by structured series with named sources and methodology — plus web results. There is no LLM in the loop, so results come back in well under a second and you decide what to do with them: feed them to the model you already use, render the card, or compute on the data. You never create a Tako account or hold a Tako key. AI Reserve holds one account, each search is billed to your wallet at the published per-search rate, and every search appears in your usage analytics under the model tako-search (or tako-search-deep).

Opt-in by construction. Nothing on the gateway calls Tako unless you call /v1/search. Ordinary chat completions never trigger a search. The recommended pattern is a tool your agent calls only when a turn needs a live number — see Use it as a tool.

Quickstart

curl -s https://api.aireserve.com/v1/search \
  -H "Authorization: Bearer $AIRESERVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "What is the price of Silver?"}'

{
  "cards": [
    {
      "card_id": "KfYeym50vtsF93LMsIFW",
      "title": "Silver Spot Price (USD/oz)",
      "description": "Spot price of silver in US dollars per troy ounce, updated intraday.",
      "webpage_url": "https://tako.com/card/KfYeym50vtsF93LMsIFW/",
      "image_url": "https://tako.com/api/v1/image/KfYeym50vtsF93LMsIFW/",
      "embed_url": "https://tako.com/embed/KfYeym50vtsF93LMsIFW/",
      "sources": [{ "source_name": "LBMA", "source_index": "tako" }]
    }
  ],
  "web_results": [{ "title": "Silver price today", "url": "https://..." }],
  "request_id": "f20f965b-6bbd-40df-b50b-a8861f34df24",
  "aireserve": { "request_id": "6b1d…", "model": "tako-search" }
}

The request and response bodies are Tako’s own Search API shapes, so Tako’s SDKs and docs apply unchanged — point them at https://api.aireserve.com/v1 with your AI Reserve key. The only differences: Tako’s usage block is not returned (billing is in your AI Reserve ledger), and every response carries an aireserve envelope with the request id to quote to support and the model the search billed under.

Request

Field	Type	Default	Notes
`query`	string	—	Required, 1–2,000 characters. Add context for relevance: `"MSFT stock price last 6 months"`, not `"MSFT"`.
`effort`	enum	`fast`	`instant` (cached cards, fastest), `fast` (balanced), `deep` (wider retrieval + rerank; billed as `tako-search-deep`).
`sources`	object	data + web	Keys select indexes: `{ "data": {} }`, `{ "web": {} }`, or both. Each takes `count` (1–20) and `include_contents`.
`country_code`	string	`US`	ISO 3166-1 alpha-2.
`locale`	string	`en-US`	BCP-47.
`timezone`	string	—	IANA timezone, e.g. `America/New_York`.
`output_settings`	object	—	`image_dark_mode`, `force_refresh` (`instant` only).

Double quotes in query force a phrase to be one entity, with an optional type label: "\"Tesla\":PRODUCT price". Every quote must be paired or Tako ignores all of them.

sources is an object, not an array. {"sources": ["data"]} is rejected with 400; use {"sources": {"data": {}}}.

Use it as a tool

Register search as a function the model can call. The model decides when a turn needs live data — typically a minority of turns — so you pay per search only when it matters, and the rest of your traffic is untouched.

from openai import OpenAI
import httpx, json, os

client = OpenAI(base_url="https://api.aireserve.com/v1", api_key=os.environ["AIRESERVE_API_KEY"])

TOOLS = [{
    "type": "function",
    "function": {
        "name": "live_search",
        "description": "Look up a current number or live fact (prices, filings, macro series, "
                       "scores, weather). Returns knowledge cards with sources plus web results.",
        "parameters": {
            "type": "object",
            "properties": {"query": {"type": "string"}},
            "required": ["query"],
        },
    },
}]

def live_search(query: str) -> dict:
    r = httpx.post(
        "https://api.aireserve.com/v1/search",
        headers={"Authorization": f"Bearer {os.environ['AIRESERVE_API_KEY']}"},
        json={"query": query, "sources": {"data": {"count": 3}, "web": {"count": 3}}},
        timeout=60,
    )
    r.raise_for_status()
    return r.json()

messages = [{"role": "user", "content": "How has silver moved this month, and why?"}]
response = client.chat.completions.create(model="gpt-5.5", messages=messages, tools=TOOLS)
choice = response.choices[0]
if choice.message.tool_calls:
    messages.append(choice.message)
    for call in choice.message.tool_calls:
        result = live_search(**json.loads(call.function.arguments))
        messages.append({"role": "tool", "tool_call_id": call.id, "content": json.dumps(result)})
    response = client.chat.completions.create(model="gpt-5.5", messages=messages, tools=TOOLS)
print(response.choices[0].message.content)

Render cards[].embed_url in an iframe for the interactive chart, or cards[].image_url for a static image; show cards[].sources as the attribution.

Billing

Model	Effort	Billed
`tako-search`	`instant`, `fast`	$0.007 per search ($7/1K)
`tako-search-deep`	`deep`	$0.012 per search ($12/1K)

Rates match Tako’s published list prices. Each search is one row in your usage analytics under those model names. The wallet reservation equals the settlement because the price is known before the call; a search that fails — at the provider, on a timeout, or because the surface is not configured — is never charged. Current rates are always on the pricing page.

Data handling

Search queries are sent to Tako Inc. (United States). Tako excludes paid-plan queries from training use but retains them under its privacy policy, and offers zero-data-retention only under an enterprise agreement that the platform account is not on. Live search therefore carries the data-retention consent gate: an organization admin accepts the disclosure once in the portal before the first search; until then the route answers 403. Do not put personal information in queries. Details on the data-handling page.

Errors

Status	Meaning
`400`	Malformed request — Tako’s validation message is relayed.
`402`	Spend cap exceeded or insufficient wallet balance.
`403`	Not a client-scoped key, model not on the key’s allowlist, or retention consent missing.
`429`	Rate limit exceeded.
`503`	Live search is not configured on this deployment, or the provider is unavailable. Retry.
`504`	The provider timed out. Retry.

Getting started

Connect your tool

GPU Infrastructure

Containers & orchestration

Capabilities

Migrate

Performance

Data & privacy

Reliability

Quickstart

Request

Use it as a tool

Billing

Data handling

Errors

​Quickstart

​Request

​Use it as a tool

​Billing

​Data handling

​Errors

Quickstart

Request

Use it as a tool

Billing

Data handling

Errors