---
title: "Fetch search result content"
method: POST
path: "/search/{id}/contents"
tags: ["Search"]
---

# Fetch search result content

`POST /search/{id}/contents`

## Request

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

Retrieves selected results from a retained search. Provide exactly one of
result_ids or limit; the latter fetches the top results. Content defaults to
source:auto. Responses preserve result_ids order. Unknown result IDs are rejected before retrieval starts.
Missing, expired, or inaccessible searches return 404. Once retrieval begins,
return one outcome per selected result, including timeout entries for work
unfinished at the overall deadline. Browser retrievals run sequentially in
result order, so later results may time out when earlier pages are slow.
X-Request-Id identifies this request separately from the search resource.

## Path parameters

- `id` string, required

## Request body

- union
  - object
    - `content` SearchContentOptions
      - `browser` SearchBrowserOptions
        - `browser_id` string: Existing browser session ID authorized for the caller and selected project. Reuses its cookies, proxy, and browser configuration; requests follow that browser's existing network access behavior, with no additional destination allowlist in this endpoint. Kernel does not delete a caller-supplied browser. Render mode uses a temporary tab; website activity may still change shared cookies and storage. When omitted and any result needs browser retrieval, Kernel creates one temporary browser for the request using the dashboard launch defaults (headful, stealth, default proxy), tags it with search_id, and deletes it when the request finishes. It is billed and counts toward browser concurrency like any other browser. A concurrency rejection returns 429 for source=browser; for source=auto, results with retained content are still returned and the rest report the rejection.
        - `mode` 'curl' | 'render': Curl uses the browser HTTP stack without navigation or JavaScript execution. Render navigates a temporary page and extracts from its DOM. The selected mode is used for the retrieval.
      - `format` 'markdown' | 'text'
      - `max_age_hours` integer: For source=auto, maximum acceptable age of retained provider content, measured from when the search received it from the provider. A value of 0 disables reuse of retained content, so every result is fetched through a browser. source=provider reuses retained provider content without freshness validation. source=browser always fetches through a browser and does not use this age limit.
      - `max_chars` integer: Per-result Unicode character limit after extraction. Retained provider content cannot exceed what was stored at search time; such results report truncated when the stored text was already truncated.
      - `source` 'auto' | 'provider' | 'browser': auto uses retained provider content within max_age_hours; for deferred retrieval it falls back to a Kernel browser (caller-supplied or temporary) for results without it. Inline retrieval never uses a browser. provider reuses retained provider content when available, without freshness validation, and never provisions a browser. browser fetches each URL through a Kernel browser, either caller-supplied or temporary. No option makes a new provider request. Defaults to auto for both inline and deferred retrieval. Missing documents produce per-result unavailable outcomes, not request failures.
      - `timeout_ms` integer: Per-result deadline including capacity acquisition, retrieval, and extraction. Also bounded by the overall request deadline.
    - `limit` integer: Maximum number of search results to fetch when result_ids is omitted, starting from rank 1. Mutually exclusive with result_ids.
    - `result_ids` string[], required: Kernel-generated IDs from the referenced retained search, in desired response order. They are not provider-standard IDs. Mutually exclusive with limit.
    - `timeout_ms` integer: Overall deadline across all selected results.
  - object
    - `content` SearchContentOptions
      - `browser` SearchBrowserOptions
        - `browser_id` string: Existing browser session ID authorized for the caller and selected project. Reuses its cookies, proxy, and browser configuration; requests follow that browser's existing network access behavior, with no additional destination allowlist in this endpoint. Kernel does not delete a caller-supplied browser. Render mode uses a temporary tab; website activity may still change shared cookies and storage. When omitted and any result needs browser retrieval, Kernel creates one temporary browser for the request using the dashboard launch defaults (headful, stealth, default proxy), tags it with search_id, and deletes it when the request finishes. It is billed and counts toward browser concurrency like any other browser. A concurrency rejection returns 429 for source=browser; for source=auto, results with retained content are still returned and the rest report the rejection.
        - `mode` 'curl' | 'render': Curl uses the browser HTTP stack without navigation or JavaScript execution. Render navigates a temporary page and extracts from its DOM. The selected mode is used for the retrieval.
      - `format` 'markdown' | 'text'
      - `max_age_hours` integer: For source=auto, maximum acceptable age of retained provider content, measured from when the search received it from the provider. A value of 0 disables reuse of retained content, so every result is fetched through a browser. source=provider reuses retained provider content without freshness validation. source=browser always fetches through a browser and does not use this age limit.
      - `max_chars` integer: Per-result Unicode character limit after extraction. Retained provider content cannot exceed what was stored at search time; such results report truncated when the stored text was already truncated.
      - `source` 'auto' | 'provider' | 'browser': auto uses retained provider content within max_age_hours; for deferred retrieval it falls back to a Kernel browser (caller-supplied or temporary) for results without it. Inline retrieval never uses a browser. provider reuses retained provider content when available, without freshness validation, and never provisions a browser. browser fetches each URL through a Kernel browser, either caller-supplied or temporary. No option makes a new provider request. Defaults to auto for both inline and deferred retrieval. Missing documents produce per-result unavailable outcomes, not request failures.
      - `timeout_ms` integer: Per-result deadline including capacity acquisition, retrieval, and extraction. Also bounded by the overall request deadline.
    - `limit` integer, required: Maximum number of search results to fetch when result_ids is omitted, starting from rank 1. Mutually exclusive with result_ids.
    - `result_ids` string[]: Kernel-generated IDs from the referenced retained search, in desired response order. They are not provider-standard IDs. Mutually exclusive with limit.
    - `timeout_ms` integer: Overall deadline across all selected results.

## Response `200`

One outcome per selected result, even if every fetch fails. Arrays are never null.

- SearchContentsResponse
  - `contents` SearchContentResult[], required
    - `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 fetched the content, or received it from the provider for retained content.
    - `final_url` string, uri: Final retrieval URL after redirects when known. Curl mode follows up to 5 redirects.
    - `format` 'markdown' | 'text'
    - `http_status` integer: Final target HTTP status when known.
    - `method` 'provider' | 'browser_curl' | 'browser_render': Original retrieval method.
    - `result_id` string, required
    - `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 the content was cut short, by max_chars or because the page exceeded the 1 MiB read limit.
    - `url` string, uri, required: Original result URL.
  - `search_id` string, required
  - `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

- `400`: Bad Request – invalid input
- `401`: Unauthorized – missing or invalid authorization token
- `403`: Forbidden – insufficient permissions or plan
- `404`: Resource not found
- `429`: Too Many Requests – rate limit exceeded
- `500`: Internal Server Error
- `503`: No provider is currently available for the request.

## Changes

- **2026-09-30** `4f43b1518ec4`: 1 breaking, 5 info
  - the `result_ids` request property's minItems was increased to `1`
  - the `limit` request property default value `10` was removed
  - added the non-success response with the status `429`
  - added the non-success response with the status `500`
  - …2 more
- **2026-09-22** `c5f760559289`: 1 info
  - endpoint added

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

---

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