{"id":"post_search_api_result_contract","kind":"post","language":"en","slug":"what-should-a-search-api-return-to-an-agent","title":"What should a search API return to an agent?","summary":"Valyu, Exa, and Parallel return different combinations of links, passages, dates, and diagnostics. Here is the evidence contract an agent needs to build around their results.","directAnswer":"An agent-ready search result needs a resolvable source URL, a relevant passage or page text, available publication metadata, and request-level status. A title or ranking score does not prove a claim. The application must record its own fetch time, check the passage against the original source, and keep publication, retrieval, and effective dates separate.","publishedAt":"2026-09-25","updatedAt":"2026-09-25","author":"Ada Vale","authorRole":"Technical writer","topic":"Search Infrastructure","tags":["search","tools","reliability","infrastructure"],"image":"/images/uploads/search-api-gateway-braces.jpg","imageAlt":"Black brace-shaped gateway framing a cream response sheet with four labeled fields on a vermilion background","featured":false,"readingMinutes":7,"seoTitle":"What a Search API Should Return to an Agent","seoDescription":"Compare the documented Valyu, Exa, and Parallel search response fields—and learn which source, passage, date, and diagnostic checks an agent must add before citing a result.","targetQuestion":"What fields should a search API return for a verifiable agent answer?","keyTakeaways":["A provider request ID traces the search call; it is not a stable identifier for the source document.","Valyu includes extracted content, source classification, and cost fields; publication metadata is not guaranteed on every result.","Exa's highlights or full text must be requested through contents; Parallel Search returns excerpts and uses Extract for full page content.","Publication date, fetch time, and the date a fact became effective answer different questions.","Warnings, partial responses, and missing passages belong in the agent's evidence record, not only in server logs."],"sources":[{"title":"Valyu Search endpoint reference","url":"https://docs.valyu.ai/api-reference/endpoint/search.md","publisher":"Valyu"},{"title":"Valyu Search quickstart","url":"https://docs.valyu.ai/search/quickstart","publisher":"Valyu"},{"title":"Exa Search API reference","url":"https://exa.ai/docs/reference/search","publisher":"Exa"},{"title":"Exa Search API guide for coding agents","url":"https://exa.ai/docs/reference/search-api-guide-for-coding-agents","publisher":"Exa"},{"title":"Exa Contents API guide for coding agents","url":"https://exa.ai/docs/reference/contents-api-guide-for-coding-agents","publisher":"Exa"},{"title":"Parallel Search API reference","url":"https://docs.parallel.ai/api-reference/search/search","publisher":"Parallel"},{"title":"Parallel Search migration guide","url":"https://docs.parallel.ai/search/migrate-to-parallel","publisher":"Parallel"},{"title":"Parallel Extract API reference","url":"https://docs.parallel.ai/api-reference/extract/extract","publisher":"Parallel"},{"title":"RFC 9110: HTTP Semantics","url":"https://www.rfc-editor.org/rfc/rfc9110.html","publisher":"RFC Editor"}],"revisions":[{"date":"2026-09-25","summary":"Checked Valyu, Exa, and Parallel response contracts against their official documentation and inspected a live Valyu response shape."}],"redirectFrom":[],"definitions":[{"term":"Search request ID","definition":"A provider-generated identifier for one search operation, useful for tracing that call; it does not identify or preserve a version of the source page."},{"term":"Evidence record","definition":"An application-level record linking a specific claim to a source URL, supporting passage, relevant dates, and the search or fetch operation that supplied it."}],"statistics":[],"expertQuotes":[],"comparisonTables":[],"faqs":[{"question":"Is a search result URL enough to support a citation?","answer":"No. The URL tells an agent where to look. Before citing a claim, it should inspect the source and retain the passage or data field that actually supports the statement, along with the relevant scope and date."},{"question":"Do publication-date fields tell an agent when a page was fetched?","answer":"No. Publication metadata describes when the source was published if that date is known. The agent should record its own retrieval time, and separately identify when the underlying fact became effective."},{"question":"Can an agent compare relevance scores across search providers?","answer":"Not as a common measure of truth or quality. Relevance scores, when supplied, reflect a provider's ranking system; Parallel's documented Search response does not return a per-result score. Verify the source and claim instead."},{"question":"What should an agent do when a search response is partial?","answer":"Keep the successful results, but record the partial status and any warnings or per-source errors. Retry failed sources when appropriate, and do not claim that the search was complete or that missing results mean no evidence exists."}],"ctas":[],"imageCredit":"Search for Agents","imageLicense":"All rights reserved","qualityScore":94,"url":"https://www.searchforagents.com/blog/what-should-a-search-api-return-to-an-agent","body":"An agent can find a convincing result and still be unable to defend the answer it writes from it. A title and URL identify a lead. A passage gives the agent something to inspect. Neither establishes that the page is authoritative for the question, that the passage is complete, or that it was true on the date the user cares about.\n\nThat makes a search API response an **evidence handoff**, not an answer. We checked the published Search contracts of **Valyu, Exa, and Parallel** on 25 September 2026 and inspected one live Valyu response for its field names. The three code examples are **raw JSON request bodies**, not cURL commands, SDK calls, or captured provider responses; authentication headers are omitted. They compare documented output shapes and integration decisions; **they are not matched-query tests of relevance, latency, or price**. We did not make live Exa or Parallel API requests.\n\n**Disclosure:** Search for Agents is produced by Valyu. Its Search API is one of three examples here; the same source-verification requirements apply to all three.\n\n## First decide what the agent has to prove\n\nSuppose an agent needs to identify the original specification for HTTP semantics. A search for “RFC 9110 HTTP Semantics” may return the [RFC Editor's copy of RFC 9110](https://www.rfc-editor.org/rfc/rfc9110.html), another page quoting it, or a summary. The result with the best excerpt might be useful for discovery. To answer which document is the specification, the agent should still open the RFC Editor's record and identify **RFC 9110**, rather than promoting a result title or ranking position into authority.\n\nThe same separation matters for a changing page. A result's publication date describes one possible property of the source; it does not tell us when the agent fetched its text or when a policy described inside it took effect. Those latter dates need their own fields in the application, even when the search provider returns useful metadata.\n\nAn agent-ready handoff needs five pieces:\n\n| Need | Minimum usable information | What still needs checking |\n| --- | --- | --- |\n| **Source identity** | Resolving URL, title, and provider result ID if available | Whether the page is the original record and whether its URL still serves the same content |\n| **Evidence** | Extracted page text or a relevant excerpt | Whether the exact claim appears in context rather than only in a generated summary |\n| **Provenance** | Provider source classification and available author or publication metadata | Which organization issued the underlying statement, not merely which index found it |\n| **Time** | Any source publication date | The application's fetch time, the source version, and the effective date of the claim |\n| **Execution state** | Request identifier, warnings or error status, and available usage information | Whether a source failed, content was truncated, or the response is incomplete |\n\nThese are requirements for the *consumer* of search, not a claim that any single vendor returns every field in this table.\n\n## Example 1: Valyu returns content with source and cost context\n\nThe [Valyu Search reference](https://docs.valyu.ai/api-reference/endpoint/search.md) describes a `POST /v1/search` request with a `query` and controls such as `search_type`, `max_num_results`, and `response_length`. A result has an `id`, `title`, `url`, extracted Markdown `content`, a `source` identifier, `source_type`, `price`, and `length`. Fields such as `publication_date`, `doi`, and `relevance_score` depend on the result and search mode; an agent must allow missing dates rather than fill them in.\n\nFor the RFC Editor question, the documented request shape permits:\n\n```json\n{\n  \"query\": \"Find the RFC Editor's RFC 9110 HTTP Semantics specification\",\n  \"search_type\": \"web\",\n  \"max_num_results\": 3,\n  \"response_length\": 2000\n}\n```\n\nAt the response level, `tx_id` identifies the operation, `results_by_source` counts source categories, and `total_deduction_dollars` reports spend. We checked those field names against the [quickstart](https://docs.valyu.ai/search/quickstart) and a live web-search response. The response included a `crawl_date` on that occasion, but the documented result contract we inspected does **not** require it. Our agent would still record its own fetch timestamp.\n\nValyu's `content` can save an immediate page fetch, but the [documented `response_length` limit](https://docs.valyu.ai/api-reference/endpoint/search.md) can truncate that text. If the decisive sentence falls beyond the returned portion, absence from `content` is not evidence that the source lacks it. A `source_type` of `paper` or `website` describes the kind of result; it does not certify the paper's conclusion or the website's authority.\n\nThe API reference also documents **HTTP 206** for a processed search when some sources failed **or no results were found**. A 206 alone does not tell the agent which happened: inspect the returned results and error or warning fields before claiming the search was complete, empty, or unusable.\n\n## Example 2: Exa makes the evidence view a request choice\n\n[Exa Search](https://exa.ai/docs/reference/search) takes a `query` and returns results with metadata such as `id`, `url`, `title`, and `publishedDate` when available. Its [Search guide](https://exa.ai/docs/reference/search-api-guide-for-coding-agents) recommends asking for `contents: { highlights: true }` when the agent needs passages; `contents.text` requests the broader cleaned page body. Search results contain **what was requested under `contents`**, so a link-only response should not be treated as though a passage was verified.\n\nFor the same task, this request asks Exa to include passages:\n\n```json\n{\n  \"query\": \"RFC Editor RFC 9110 HTTP Semantics\",\n  \"numResults\": 3,\n  \"contents\": { \"highlights\": true }\n}\n```\n\nExa includes a top-level `requestId` and a `costDollars` object. Its Search reference describes that cost as an **endpoint-dependent estimate**, not necessarily the final billed amount. The `requestId` makes a call traceable, while the result's `id` or `url` identifies a discovered page; neither is an immutable snapshot of what the page said.\n\nFor changing pages, `contents.maxAgeHours` controls how old cached extracted content may be before Exa attempts another fetch. Exa explicitly distinguishes that setting from a publication-date filter. Setting a low maximum age addresses one form of stale *extraction*; it does not guarantee that a new fetch succeeds or make an old underlying claim current. [Exa's Contents guide](https://exa.ai/docs/reference/contents-api-guide-for-coding-agents) also says a separate Contents request can check per-URL `statuses` when fetching specified pages.\n\n## Example 3: Parallel starts with excerpts and request warnings\n\nThe current [Parallel Search endpoint](https://docs.parallel.ai/api-reference/search/search) uses `POST /v1/search` with `search_queries` and an optional natural-language `objective`. Its documented result fields include `url`, `title`, `publish_date` (which can be null), and an `excerpts` array. The response includes `search_id`, `session_id`, and optional `warnings` and `usage` fields. `session_id` can carry context across later Search and Extract calls; `search_id` refers to this search, not to a version of a source document.\n\nParallel represents that task with short queries and an optional objective:\n\n```json\n{\n  \"search_queries\": [\"RFC 9110 HTTP Semantics\"],\n  \"objective\": \"Find the RFC Editor's original RFC 9110 specification.\"\n}\n```\n\nThe [migration guide](https://docs.parallel.ai/search/migrate-to-parallel) is explicit about a tradeoff: Search returns compressed excerpts rather than complete page bodies and does **not** provide a per-result relevance score. If the agent needs a wider passage, the [Extract API](https://docs.parallel.ai/api-reference/extract/extract) has a separate `full_content` field and per-URL errors. Preserve the ranked order rather than manufacturing a score from position, and inspect `warnings` before assuming every requested constraint was honored.\n\nParallel's `publish_date`, like the dates in the other examples, is source metadata when available. It is not the timestamp of your application receiving the answer. The agent still needs to attach that timestamp and reopen the original source if a compressed excerpt leaves out the qualification that changes the meaning of a claim.\n\n## Do not normalize away the differences\n\nAn application may want one internal record format, but a flat `score` and a `snippet` field would erase important distinctions. Valyu's extracted `content`, Exa's requested `highlights` or `text`, and Parallel's default `excerpts` are different views with different completeness guarantees. The dollar fields are not directly comparable either: Valyu reports `total_deduction_dollars`, Exa describes `costDollars` as estimated, and Parallel exposes `usage` metrics. None makes a claim more credible simply because the call cost more.\n\nKeep the raw provider response alongside a small normalized evidence record: **provider and request ID; source URL and any document identifier available; returned excerpt or text; which content view was requested; any publication date; the application's retrieval time; warnings, partial failures, or per-URL errors; and a pointer to the exact passage checked on the original page.** Set unknown fields to unknown. Do not transform a missing publication date into today's date, or treat a provider's request ID as a document ID.\n\nBefore the agent cites anything, ask whether it can reopen the URL, locate the claimed passage, and state which source and date govern the answer. If it cannot, the search response is still a useful lead—but the claim has not passed verification. The [web-result investigation](/blog/when-can-an-agent-trust-a-web-search-result) shows that boundary in a live source dispute; the [evidence-first evaluation brief](/research/evidence-first-agent-evaluation) explains how to check the resulting answer independently.\n\n*Method note: API field names and request behavior above were checked against each provider's published documentation on 25 September 2026. One Valyu response shape was also inspected directly. Exa and Parallel examples describe documented interfaces, not observed results from live calls; no claims about relative retrieval quality are made.*","quality":{"score":94,"threshold":85,"ready":true,"checks":[{"id":"direct-answer","label":"Direct answer","status":"pass","points":12,"maxPoints":12,"evidence":"357 characters"},{"id":"target-question","label":"Target question","status":"pass","points":8,"maxPoints":8,"evidence":"Written as an explicit question"},{"id":"key-takeaways","label":"Key takeaways","status":"pass","points":8,"maxPoints":8,"evidence":"5 takeaways"},{"id":"source-depth","label":"Source depth","status":"pass","points":14,"maxPoints":14,"evidence":"9 sources"},{"id":"source-dates","label":"Source dates","status":"warn","points":0,"maxPoints":6,"evidence":"0 of 9 sources include publication dates"},{"id":"section-depth","label":"Section depth","status":"pass","points":12,"maxPoints":12,"evidence":"5 H2 sections"},{"id":"heading-integrity","label":"Heading integrity","status":"pass","points":8,"maxPoints":8,"evidence":"No body H1 or skipped heading levels"},{"id":"body-substance","label":"Body substance","status":"pass","points":10,"maxPoints":10,"evidence":"1483 words"},{"id":"internal-links","label":"Internal links","status":"pass","points":6,"maxPoints":6,"evidence":"Includes a site-relative internal link"},{"id":"date-integrity","label":"Date integrity","status":"pass","points":8,"maxPoints":8,"evidence":"2026-09-25 published; 2026-09-25 updated"},{"id":"image-alt","label":"Image description","status":"pass","points":4,"maxPoints":4,"evidence":"108 characters"},{"id":"author-context","label":"Author context","status":"pass","points":4,"maxPoints":4,"evidence":"Ada Vale - Technical writer"}],"recommendations":["0 of 9 sources include publication dates"]},"provenance":{"version":"sfa.provenance.v1","sourcePath":"content/posts/what-should-a-search-api-return-to-an-agent.md","canonicalMarkdownHash":"b9cef93916d5a4212d9dd79d2d4f6c3c0d6b8abc21a28194261a9298b5251864","contentHash":"0e215f501da898b2d97a673aa16509bad4a598d748e858828cd63ac053208dda","schemaVersion":"post.v1","commit":"86eeb0c2cfe77a7d66370be2b282a2e8c1f0c055"},"sourceBundleUrl":"https://www.searchforagents.com/api/v1/content/post_search_api_result_contract/source-bundle","representations":{"html":"https://www.searchforagents.com/blog/what-should-a-search-api-return-to-an-agent","markdown":"https://www.searchforagents.com/blog/what-should-a-search-api-return-to-an-agent.md","json":"https://www.searchforagents.com/blog/what-should-a-search-api-return-to-an-agent.json"},"alternates":{"en":"https://www.searchforagents.com/blog/what-should-a-search-api-return-to-an-agent","x-default":"https://www.searchforagents.com/blog/what-should-a-search-api-return-to-an-agent"}}