Create a grounded response (streaming)

POST/v1/responses

Runs the grounded search pipeline (Plan → Collect → Process → Analyze) and streams results as Server-Sent Events following the OpenAI Responses API format.

Body ParametersJSONExpand Collapse

input: string or array of object { content, role }

User message string or array of input items.

One of the following:

UnionMember0 = string

UnionMember1 = array of object { content, role }

content: optional string or unknown

One of the following:

UnionMember0 = string

UnionMember1 = unknown

role: optional string

effort: optional "low" or "medium" or "high" or "max"

Anthropic API effort level. Defaults to high.

One of the following:

"low"

"medium"

"high"

"max"

model: optional string

Model ID, e.g. "grounded-sonnet" or "grounded-opus".

params: optional object { exaCategory, exaExcludeDomains, exaExcludeText, 6 more }

Pipeline parameters. Merged with the high preset defaults.

exaCategory: optional "" or "company" or "research paper" or 6 more

One of the following:

"company"

"research paper"

"news"

"pdf"

"github"

"tweet"

"personal site"

"financial report"

exaExcludeDomains: optional array of string

exaExcludeText: optional array of string

exaIncludeDomains: optional array of string

exaIncludeText: optional array of string

exaNumResults: optional number

exaStartPublishedDate: optional string

ISO date (YYYY-MM-DD)

maxSnippetsPerSource: optional number

planMaxQueries: optional number

stream: optional boolean

Must be true — only streaming mode is supported.

ReturnsExpand Collapse

ResponseCreated = object { response, type }

response: object { id, created_at, model, 3 more }

id: string

created_at: number

model: string

object: "response"

output: array of unknown

status: "in_progress"

type: "response.created"

ResponseInProgress = object { response, type }

response: object { id, object, status }

id: string

object: "response"

status: "in_progress"

type: "response.in_progress"

ResponsePipelineStage = object { pipeline_stage, type }

pipeline_stage: object { stage, status } or object { duration_ms, intent, queries, 2 more } or object { stage, status, total_queries } or 7 more

One of the following:

UnionMember0 = object { stage, status }

stage: "planning"

status: "in_progress"

UnionMember1 = object { duration_ms, intent, queries, 2 more }

duration_ms: number

intent: string

queries: array of object { desired_snippets, query, startPublishedDate }

desired_snippets: string

Describes what snippets to extract from results of this query.

query: string

startPublishedDate: optional string

Optional ISO date — only return results published after this date.

stage: "planning"

status: "done"

UnionMember2 = object { stage, status, total_queries }

stage: "collecting"

status: "in_progress"

total_queries: number

UnionMember3 = object { completed_queries, sources, stage, 2 more }

completed_queries: number

sources: array of CollectedSourceSummary { author, favicon, image, 8 more }

author: string

favicon: string

image: string

published_date: string

query_index: number

query_indices: array of number

result_index: number

score: number

title: string

url: string

providers: optional array of string

Provider names that returned this URL (admin-only).

stage: "collecting"

status: "progress"

total_queries: number

UnionMember4 = object { duration_ms, sources, stage, status }

duration_ms: number

sources: array of CollectedSourceSummary { author, favicon, image, 8 more }

author: string

favicon: string

image: string

published_date: string

query_index: number

query_indices: array of number

result_index: number

score: number

title: string

url: string

providers: optional array of string

Provider names that returned this URL (admin-only).

stage: "collecting"

status: "done"

UnionMember5 = object { stage, status, total_sources }

stage: "processing"

status: "in_progress"

total_sources: number

UnionMember6 = object { completed_sources, snippets, stage, 2 more }

completed_sources: number

snippets: array of Snippet { source_index, text, verified, num }

source_index: number

text: string

The relevant passage extracted from the source.

verified: boolean

Whether the snippet text was verified as a substring of the source document.

num: optional number

Sequential number assigned to verified snippets (1-based). Unverified snippets have no num.

stage: "processing"

status: "progress"

total_sources: number

UnionMember7 = object { duration_ms, snippets, stage, status }

duration_ms: number

snippets: array of Snippet { source_index, text, verified, num }

source_index: number

text: string

The relevant passage extracted from the source.

verified: boolean

Whether the snippet text was verified as a substring of the source document.

num: optional number

Sequential number assigned to verified snippets (1-based). Unverified snippets have no num.

stage: "processing"

status: "done"

UnionMember8 = object { stage, status }

stage: "analysis"

status: "in_progress"

UnionMember9 = object { duration_ms, stage, status }

duration_ms: number

stage: "analysis"

status: "done"

type: "response.pipeline_stage"

ResponseOutputItemAdded = object { item, output_index, type }

item: object { id, content, role, type }

id: string

content: array of unknown

role: "assistant"

type: "message"

output_index: number

type: "response.output_item.added"

ResponseOutputItemDone = object { item, output_index, type }

item: object { id, type }

id: string

type: "message"

output_index: number

type: "response.output_item.done"

ResponseContentPartAdded = object { content_index, item_id, part, type }

content_index: number

item_id: string

part: object { annotations, text, type }

annotations: array of unknown

text: string

type: "output_text"

type: "response.content_part.added"

ResponseContentPartDone = object { content_index, item_id, part, type }

content_index: number

item_id: string

part: object { annotations, text, type }

annotations: array of object { end_index, start_index, title, 3 more }

end_index: number

start_index: number

title: string

type: "url_citation"

url: string

cited_text: optional string

text: string

type: "output_text"

type: "response.content_part.done"

ResponseOutputTextDelta = object { content_index, delta, item_id, type }

content_index: number

delta: string

item_id: string

type: "response.output_text.delta"

ResponseCompleted = object { response, type }

response: object { id, object, output, 2 more }

id: string

object: "response"

output: array of unknown

status: "completed"

usage: optional object { cache_creation_input_tokens, cache_read_input_tokens, exa_cost_usd, 4 more }

cache_creation_input_tokens: optional number

cache_read_input_tokens: optional number

exa_cost_usd: optional number

input_tokens: optional number

output_tokens: optional number

search_cost_usd: optional number

total_cost_usd: optional number

type: "response.completed"

ResponseFailed = object { response, type }

response: object { id, error, object, status }

id: string

error: object { code, message, type }

code: string

message: string

type: string

object: "response"

status: "failed"

type: "response.failed"