# Search

Call the Talarion search endpoint directly over HTTPS — retrieve verified assertions with a single `POST`.

  [API Playground →](https://dashboard.talarion.com/playground)
  [Create an API key →](https://dashboard.talarion.com/api-keys)

## Your first request

#### curl

```bash
curl -X POST https://api.talarion.com/v1/search \
  -H "Authorization: Bearer $TALARION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "What are the most significant AI model releases in 2026?"}'
```

#### Python

```python
import os
import requests

resp = requests.post(
    "https://api.talarion.com/v1/search",
    headers={"Authorization": f"Bearer {os.environ['TALARION_API_KEY']}"},
    json={"query": "What are the most significant AI model releases in 2026?"},
)
resp.raise_for_status()

for fact in resp.json()["results"]:
    print(f"{fact['question']} → {fact['answer']} (true by {fact['true_by']})")
    for url in fact["sources"]:
        print(f"    source: {url}")
```

#### TypeScript

```typescript
const res = await fetch("https://api.talarion.com/v1/search", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.TALARION_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    query: "What are the most significant AI model releases in 2026?",
  }),
});

const { results } = await res.json();
console.log(results);
```

## Response

A JSON object with a `results` array. Each entry is a self-contained, current fact —
correcting a misconception the querying LLM would otherwise be operating under — with a `question`, an `answer`,
`true_by` (the date the fact was known true — ISO `YYYY-MM-DD`, or `null` when the source carries
no truth-time), and `sources`, a list of the upstream URL(s) the fact is drawn from. By default
entries are ordered with the most recent `true_by` first; set `timeline: false` to order by
relevance instead. A response is never empty; a question returns the nearest available facts.
See [Overview](/overview) for how to use them.

```json
{
  "results": [
    {
      "question": "What flagship AI model did Anthropic release in May 2026?",
      "answer": "Claude Opus 4.8.",
      "true_by": "2026-05-15",
      "sources": ["https://www.anthropic.com/news/claude-opus-4-8"]
    },
    {
      "question": "What is the estimated total amount major tech companies will spend on AI data centers in 2026?",
      "answer": "$650 billion.",
      "true_by": "2026-03-01",
      "sources": [
        "https://www.cnbc.com/2026/03/01/big-tech-ai-data-center-spending-2026.html",
        "https://www.reuters.com/technology/ai-capex-2026-forecast/"
      ]
    }
  ]
}
```

The shape is built for an LLM to consume rather than a person to read, with terse
`question`/`answer` pairs stamped with a date and sources grounding a model most reliably.

## Parameters

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `query` | string | Yes | The search question you want caught up on — e.g. "How is insurance coverage of GLP-1 obesity drugs changing?". One focused question about one topic retrieves best. |
| `model_id` | string | No | Your model as an OpenRouter id (e.g. `anthropic/claude-opus-4.8`). Filters results to facts that postdate your model's training cutoff. |
| `k` | integer | No | Number of facts to return. Defaults to `20`; clamped to the range `10`–`100`. |
| `timeline` | boolean | No | Result ordering. `true` (default): most recent `true_by` first. `false`: ordered by relevance. |
| `true_by_min` | datetime | No | Only return facts with `true_by` on or after this ISO 8601 datetime. Overrides the `model_id`-derived training-cutoff floor. Naive datetimes are treated as UTC. |
| `true_by_max` | datetime | No | Only return facts with `true_by` on or before this ISO 8601 datetime — e.g. for date-boxed backtesting. Must be after `true_by_min`. |

## Errors & limits

| Status | Meaning |
|--------|---------|
| `401` | Missing or invalid API key. |
| `402` | Free-tier monthly call limit reached (1,000 calls/month). Upgrade in [Billing](https://dashboard.talarion.com/billing). |
| `422` | Invalid request body — e.g. an empty `query`, or `true_by_max` not after `true_by_min`. |