# Preview what an agent would retrieve, and answer, for a question

Source: https://docs.usetone.ai/reference/knowledge/search

> Runs the SAME retrieval a live turn runs, so what you see here is what the agent would get.

`POST /v1/knowledge-bases/{id}/search`
Runs the SAME retrieval a live turn runs, so what you see here is what the agent would get. Optionally generates the answer a caller would hear. `degraded: true` means embeddings were unavailable and this fell back to keyword search alone — the results are real, just weaker.

Requires the `read` scope.

## Parameters

| Name | In | | Meaning |
|---|---|---|---|
| `id` | path | required | The knowledge base's id. |

## Request body

| Field | Type | | Meaning |
|---|---|---|---|
| `answer` | boolean | optional | Also generate the answer a caller would hear. Defaults on; the passage list underneath is the debugging view. Turning it off skips the generation call entirely. |
| `limit` | integer | optional | How many passages to return, 1-10. |
| `query` | string | required | What to search for, phrased as a caller would ask it. This runs the same retrieval a live turn runs, so the passages here are the passages the agent would get. |

### Example request

```json
{
  "answer": true,
  "limit": 3,
  "query": "How long do I have to return an item?"
}
```

## Response

| Field | Type | | Meaning |
|---|---|---|---|
| `answer` | string | null | required | What the agent would say. Null when answering is off or failed. |
| `answerScope` | string | null | required | What the answer was drawn from: the whole base inline, or the retrieved passages. Open set — handle an unrecognised value rather than throwing. Today: `inline`, `passages`. |
| `answerStatus` | string | required | Open set — handle an unrecognised value rather than throwing. Today: `ok`, `disabled`, `failed`, `no_context`. |
| `degraded` | boolean | required | True when embeddings were unavailable and this fell back to text search alone — the results are real, just weaker. |
| `results` | object[] | required | The passages retrieval returned, best first — the same passages a live turn would get for this query. |
| `results[].documentId` | string | required | Which document the passage came from. |
| `results[].headingPath` | string | null | required | Where the passage sits in the document’s heading structure. |
| `results[].matchedText` | boolean | required | Found by keyword match. Both can be true. |
| `results[].matchedVector` | boolean | required | Found by embedding similarity. |
| `results[].score` | number | required | Relevance, higher is better. Comparable within one response, not across responses. |
| `results[].text` | string | required | The passage itself, exactly as the agent would receive it. |

### Example response

```json
{
  "data": {
    "answer": "You can return unopened items within 30 days for a full refund.",
    "answerScope": "inline",
    "answerStatus": "ok",
    "degraded": true,
    "results": [
      {
        "documentId": "9f1c2d84-4e3a-4f6c-b902-7d1e8a33c451",
        "headingPath": "Returns > Timeframe",
        "matchedText": true,
        "matchedVector": true,
        "score": 0,
        "text": "Unopened items may be returned within 30 days of delivery for a full refund."
      }
    ]
  }
}
```