---
url: https://docs.freetheai.org/api/search.md
description: >-
  POST /v1/search - current web results with titles, links, and text excerpts
  for any model or app, using your FreeTheAI key and a small daily allowance.
---

# Search

Returns current web results for a query: title, link, and a text excerpt when available. Use them with any model or app, for example to give a model current information. Use [Answer](/api/answer) instead when you want a written answer.

`POST https://api.freetheai.org/v1/search`

## Request

::: code-group

```bash [curl]
curl https://api.freetheai.org/v1/search \
  -H "Authorization: Bearer $FTAI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "vitepress local search", "num_results": 5}'
```

```python [Python]
import os
import requests

response = requests.post(
    "https://api.freetheai.org/v1/search",
    headers={"Authorization": f"Bearer {os.environ['FTAI_KEY']}"},
    json={"query": "vitepress local search", "num_results": 5},
    timeout=60,
)
response.raise_for_status()
for result in response.json()["results"]:
    print(result["title"], result["url"])
```

```ts [TypeScript]
type SearchResult = { title: string; url: string; text?: string; publishedDate?: string }

const response = await fetch('https://api.freetheai.org/v1/search', {
  method: 'POST',
  headers: { Authorization: `Bearer ${process.env.FTAI_KEY}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({ query: 'vitepress local search', num_results: 5 }),
})
if (!response.ok) throw new Error((await response.json()).error?.message)
const { results } = (await response.json()) as { results: SearchResult[] }
for (const r of results) console.log(r.title, r.url)
```

:::

## Body parameters

| Parameter | Type | Description |
| --- | --- | --- |
| `query` | string, **required** | What to search for, up to 1,024 characters. Short keyword queries work best. |
| `num_results` | integer | How many results to return, 1 to 25. Default 10. |

## Response

```json
{
  "query": "vitepress local search",
  "results": [
    {
      "title": "Search | VitePress",
      "url": "https://vitepress.dev/reference/default-theme-search",
      "text": "VitePress supports fuzzy full-text search using an in-browser index...",
      "publishedDate": "2025-01-20",
      "score": 0.82,
      "highlights": ["...in-browser index thanks to minisearch..."]
    }
  ],
  "suggestions": [],
  "daily_used": 3,
  "daily_limit": 50
}
```

| Field | Type | Description |
| --- | --- | --- |
| `query` | string | The query that was searched. |
| `results[].title` | string | Page title. |
| `results[].url` | string | Page link. |
| `results[].text` | string | A text excerpt from the page, when available. |
| `results[].highlights` | array of strings | Short relevant passages, when available. |
| `results[].publishedDate` | string | Publication date, when known. |
| `results[].score` | number | Relevance score, when available. |
| `suggestions` | array of strings | Related queries, when available. |
| `daily_used` | integer | Searches used today, including this one. |
| `daily_limit` | integer | Your account's daily web-search allowance. |

The `daily_limit` value in the example is only an illustration; read it from the response.

## Limits

* Every call counts against one **daily web-search allowance** shared with [`/v1/answer`](/api/answer). It is separate from your free requests and resets at 00:00 UTC.
* Identical queries within an hour return the same results.

## Errors

| Status | Meaning |
| --- | --- |
| `400` | The query is missing or too long. |
| `401` | Missing or invalid API key. |
| `429` | The daily web-search allowance is used up. It resets at 00:00 UTC. |
| `502` | No results could be fetched right now. Try again shortly. |