> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aireserve.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Live search

> Give any model current numbers and live facts — structured knowledge cards with named sources plus web results from Tako, on your AI Reserve key and wallet, billed per 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](https://tako.com):
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`).

> [!NOTE]
>
> **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](#use-it-as-a-tool).

## Quickstart

```bash theme={"dark"}
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?"}'
```

```json theme={"dark"}
{
  "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.

> [!WARNING]
>
> `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.

```python theme={"dark"}
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](https://aireserve.com/pricing).

## 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](https://privacy.aireserve.com/data-handling).

## 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. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.