# SearchResponse

Inspect the winner, source material, execution trace, warnings, and reported usage.

Canonical: https://searchsdk.dev/docs/api/response
Markdown: https://searchsdk.dev/docs/api/response.md

<a id="shape"></a>

## Response fields

> **TypeScript reference**
> The API names, code and policy behavior in this article describe the TypeScript SDK. See [your language guide](https://searchsdk.dev/docs/sdks) for its supported surface and limits.

**TypeScript · shape**

```typescript
interface SearchResponse {
  provider: string;
  results: readonly SearchResult[];
  attempts: readonly SearchAttempt[];
  warnings: readonly {
    code: 'fallback_used' | 'provider_warning';
    provider: string;
  }[];
  usage: { unit: 'usd' | 'credits'; value: number } | null;
  reuse?: 'cache' | 'inflight';
}
```

<a id="result"></a>

## Result fields

| Field | Meaning |
| --- | --- |
| `url` | Validated HTTP(S) source link. |
| `title?`, `snippet?` | Optional provider text; render as untrusted text. |
| `highlights?` | Separate passages, preserved as an array. |
| `score?` | Native score; no cross-provider normalization. |
| `provenance` | Provider ID, sourceUrl, retrievedAt, optional requestId. |

<a id="validation"></a>

## Validation and omissions

Built-in adapters validate consumed fields, including results beyond the output ceiling, before returning. A malformed consumed field rejects with `invalid_response` instead of being silently discarded. Unknown provider fields are ignored. The orchestrator also checks the normalized shape returned by custom providers, including safe URLs, provenance fields, usage, and warnings, and copies only public fields. Structural validation does not prove source truth or attribution.

- [Provenance semantics](https://searchsdk.dev/docs/reliability/provenance)
- [Warnings and usage](https://searchsdk.dev/docs/reliability/usage)