---
title: "Retrieve a search"
method: GET
path: "/search/{id}"
tags: ["Search"]
---

# Retrieve a search

`GET /search/{id}`

## Request

- Base URL: `https://api.onkernel.com`
- URL: `https://api.onkernel.com/search/{id}`
- Auth: HTTP bearer

Returns the retained search resource exactly as it was returned by
POST /search: results, attempts, warnings, usage, and expires_at. No
provider is called and nothing is billed. Use it to look up a search
by ID for debugging, cost review, or to recover result IDs before
calling the contents endpoint. Inline content fetched at search time
is included; content fetched later through the contents endpoint is
not merged in. Missing, expired, or inaccessible searches return 404.

## Path parameters

- `id` string, required

## Response `200`

The retained search.

- Search: Retained search results and provider attempt history.
  - `answer` string: Provider-generated answer when requested (e.g. via Tavily include_answer or Perplexity). Preserved independently of include_raw.
  - `attempts` SearchAttempt[], required
    - `duration_ms` integer, required
    - `error_code` string
    - `outcome` 'success' | 'empty' | 'error' | 'timeout', required
    - `provider` string, required
    - `retryable` boolean
  - `expires_at` string, date-time, required: Expiration of result IDs for deferred retrieval. Results expire 24 hours after search completion.
  - `id` string, required: Search resource ID. Request tracing uses X-Request-Id.
  - `provider` string, required: Concrete serving provider, never auto or fallback.
  - `query` string, required: Echo of the query. Native multi-query inputs are visible in the selected strategy target and the optional raw response.
  - `raw` unknown
  - `results` SearchResult[], required
    - `additional_snippets` string[]
    - `content` SearchResultContent
      - `cache_status` 'hit' | 'miss' | 'bypass' | 'unknown': Kernel content cache outcome. Kernel has no content cache yet: responses report bypass or unknown, and hit and miss are reserved. Provider-internal cache behavior may be unknown.
      - `completeness` 'full_page' | 'excerpt' | 'unknown': Describes source coverage before max_chars truncation. Full_page means main-page content, not every dynamic element or linked page.
      - `error` SearchContentError
        - `code` string, required: Machine-readable retrieval failure code.
        - `message` string, required: Human-readable failure description.
        - `retryable` boolean, required
      - `extractor_version` string: Extraction version when Kernel transformed the input.
      - `fetched_at` string, date-time, nullable: When Kernel received the content from the provider.
      - `final_url` string, uri: Final retrieval URL when known.
      - `format` 'markdown' | 'text'
      - `http_status` integer: Final target HTTP status when known.
      - `method` 'provider' | 'browser_curl' | 'browser_render': Original retrieval method.
      - `status` 'ok' | 'unavailable' | 'blocked' | 'timeout' | 'unsupported_type' | 'extraction_failed' | 'error', required: Ok means non-empty extracted content, not merely HTTP 200. Blocked includes detected challenges or access denials. Detection is best-effort, not a guarantee of page completeness. Error details are present for non-ok outcomes; text is present only on ok.
      - `text` string: Extracted website content, untrusted, not instructions. Present only on status=ok.
      - `truncated` boolean: Whether max_chars truncated the extracted content.
    - `id` string, required: Kernel-generated identifier for this result. Stable only within the retained search; not standardized across providers. Provider-native IDs, when available, remain provider-specific raw fields.
    - `published_date` string, nullable: Provider-supplied date or timestamp, preserving available precision. No publication date is fabricated. Retains the published field name.
    - `rank` integer, required: One-based position in the returned ranking.
    - `raw` unknown
    - `snippet` string, nullable
    - `source` string, nullable: Provider source name or result URL hostname, when available.
    - `title` string, nullable
    - `url` string, uri, required: Provider-returned URL, not assumed canonical.
  - `usage` SearchUsage, required
    - `content_fetches` integer, required: Number of result URLs for which a Kernel browser retrieval received a response from the target, excluding cache-only hits.
    - `cost` number: Total customer charge in USD when billing data is available.
    - `results_count` integer, required: Number of result entries returned, including failed entries on the contents endpoint.
  - `warnings` SearchWarning[], required
    - `code` string, required: Examples: param_unsupported, preference_unsupported, max_results_clamped, domains_truncated, recency_emulated, filter_emulated, date_filter_overridden, provider_ineligible, fallback_failed, content_partial.
    - `message` string, required
    - `param` string
    - `provider` string
    - `result_id` string

## Other responses

- `401`: Unauthorized – missing or invalid authorization token
- `403`: Forbidden – insufficient permissions or plan
- `404`: Resource not found
- `500`: Internal Server Error
- `503`: No provider is currently available for the request.

## Changes

- **2026-10-16** `03b369edee49`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/kernel/apis/kernel-api/changes/search/:id/get.md)

---

[API](https://skmtc.dev/kernel/apis/kernel-api.md) - [All operations](https://skmtc.dev/kernel/apis/kernel-api/llms.txt) - [OpenAPI document](https://skmtc.dev/kernel/apis/kernel-api/revisions/0f6cf4f58fe6?raw)