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

# Search Agent

> Get a cited answer from an agent that searches and reads the web on its own.

For AI agents: [docs.octen.ai/capabilities/search-agent.md](https://docs.octen.ai/capabilities/search-agent.md)

A real question rarely takes one search. Answering it means a loop of planning queries, reading pages, and checking sources, and every page in that loop costs a model tokens and time.

Octen Search Agent runs the whole loop on its own and returns only the result: a cited answer, as Markdown or as JSON in the schema you define. It works out a search strategy for each question and searches the web and news, with tiers from a single fact to a long report.

For the full list of parameters, see the [Search Agent API reference](https://docs.octen.ai/api-reference/post-search-agent.md).

## Why Search Agent

* **Depth that fits the question.** Trade depth against cost and time per task, or pay only for actual usage.
* **Structured answers.** Get JSON in the shape you define, ready to store or pass to the next step.
* **Cited answers.** Inline citations link the answer back to the pages it stands on.
* **Built for long tasks.** Tasks run in the background: follow each step live, or fetch the result when it is done.

For a quick grounded answer, use [Answer](https://docs.octen.ai/capabilities/answer.md). For long-form research reports, use [Deep Research](https://docs.octen.ai/capabilities/deep-research.md).

## How It Works

1. Send a question and pick a tier. The call returns a task id right away, or streams the task as it runs.
2. The agent works out its own search strategy: it searches the web and news and reads the pages it needs.
3. It returns a cited answer as Markdown or as JSON in your schema. Fetch the result by task id, or read it from the stream.

## Scenarios

### Look up a fact

Send the question, then fetch the answer with the returned `task_id`.

```bash theme={null}
curl -X POST https://api.octen.ai/v1/agent \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "messages": [{ "role": "user", "content": "Who won the 2026 Nobel Prize in Physiology or Medicine?" }],
    "tier": "low"
  }'
```

The task is done when `status` is `succeeded`.

```bash theme={null}
curl https://api.octen.ai/v1/agent/YOUR_TASK_ID \
  -H "x-api-key: YOUR_API_KEY"
```

### Extract structured data

Define the fields you need as a JSON Schema. The answer comes back as JSON that matches it, with citations.

```json theme={null}
{
  "messages": [{ "role": "user", "content": "Names, affiliations at the time of the award, and nationalities of the 2026 Nobel laureates in Physiology or Medicine" }],
  "response_format": {
    "type": "json_schema",
    "schema": {
      "type": "object",
      "properties": {
        "laureates": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "name": { "type": "string" },
              "affiliation": { "type": "string" },
              "nationality": { "type": "string" }
            },
            "required": ["name", "affiliation", "nationality"],
            "additionalProperties": false
          }
        }
      },
      "required": ["laureates"],
      "additionalProperties": false
    }
  }
}
```

### Show progress as it works

Stream the task to show each step in your UI. `step` chunks report every search and page read as it happens, and `content` chunks carry the answer.

```json theme={null}
{
  "messages": [{ "role": "user", "content": "Who won the 2026 Nobel Prize in Physiology or Medicine?" }],
  "stream": true
}
```

If the connection drops, the task keeps running. Fetch the result by task id.

### Ask a follow-up

Pass the earlier task's id as `previous_task_id`. The follow-up is understood in context, so send only the new question.

```json theme={null}
{
  "messages": [{ "role": "user", "content": "Which institutions were they at when they won?" }],
  "previous_task_id": "YOUR_TASK_ID"
}
```

### Go deep on a complex question

For questions that need broad coverage, `high` searches deeper and can return a long report.

```json theme={null}
{
  "messages": [{ "role": "user", "content": "Compare the 2026 EV purchase incentives in the US, the EU, and China" }],
  "tier": "high"
}
```

## Next Steps

> [card] [Try in Console](https://octen.ai/platform/search-agent)
>
> Run Search Agent live in the Octen console.

> [card] [Search Agent API Reference](https://docs.octen.ai/api-reference/post-search-agent.md)
>
> Full request/response schema.

***

Last modified on November 2, 2026


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