> ## Documentation Index > Fetch the complete documentation index at: https://docs.octen.ai/llms.txt > Use this file to discover all available pages before exploring further. # Search Agent API Reference > Runs a Search Agent task that answers a question with cited sources, as a Markdown answer or as JSON that matches your schema. ## OpenAPI ````yaml /api-reference/openapi.json post /v1/agent openapi: 3.1.0 info: title: Octen API description: >- Octen API provides Broad Search, Web Search, Image Search, Video Search, Extract, Embeddings, VL Embeddings, Answer, and Deep Research services. The Web Search API searches ranked web results with optional filters, highlights, and full content. The Image Search API searches for images from a text query or an image. The Video Search API searches for videos from a text query. The Broad Search API decomposes a query into multiple sub-queries, searches them in parallel, and returns results grouped by sub-query. The Extract API extracts clean content from URLs, with optional query-focused highlights, page classification, and multimedia resources. The Embeddings API converts text into vector representations. The VL Embeddings API converts multimodal inputs into vector representations. The Answer API decomposes queries into multiple sub-queries for comprehensive search and synthesis. The Deep Research API runs a multi-round adaptive research pipeline that produces a structured research plan, executes iterative searches, and streams a final long-form report. The Pulse Search API generates the most likely URLs for a query in about 10ms, with optional highlights and full content in standard mode. version: 1.0.0 servers: - url: https://api.octen.ai security: - bearerAuth: [] - apiKeyAuth: [] paths: /v1/agent: post: summary: Search Agent description: >- Runs a Search Agent task that answers a question with cited sources, as a Markdown answer or as JSON that matches your schema. operationId: post-search-agent requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SearchAgentRequest' examples: streamText: summary: Text answer, streamed value: messages: - role: user content: Who won the 2026 Nobel Prize in Physiology or Medicine? tier: low stream: true structuredOutput: summary: Structured output value: messages: - role: user content: >- Names, affiliations at the time of the award, and nationalities of the 2026 Nobel laureates in Physiology or Medicine tier: low response_format: type: json_schema schema: type: object properties: laureates: type: array items: type: object properties: name: type: string affiliation: type: string nationality: type: string required: - name - affiliation - nationality additionalProperties: false required: - laureates additionalProperties: false followUp: summary: Follow-up question value: messages: - role: user content: Which institutions were they at when they won? previous_task_id: agent-7f3c2a9e4b1d4c6f8a0e5b2d9c1f6a37 tier: low responses: '200': description: >- Successful Search Agent response. When `stream=false`, the task starts in `queued`. When `stream=true`, returns a stream of chunks. content: application/json: schema: oneOf: - $ref: '#/components/schemas/SearchAgentResponse' - $ref: '#/components/schemas/SearchAgentChunk' examples: nonStreaming: summary: Non-streaming response (task object) value: request_id: 20261016092031207H5RC2LJ9ZB task_id: agent-2b8e6d41c9a04f7e93d5a1c0e6b7f284 tier: low status: queued created_at: 1793608547 streamStatus: summary: 'Streaming chunk — status (type: status)' value: type: status request_id: 20261016091204118K7Q2M9XA4D created: 1793608513 task_id: agent-7f3c2a9e4b1d4c6f8a0e5b2d9c1f6a37 status: running streamStepStarted: summary: 'Streaming chunk — step started (type: step)' value: type: step request_id: 20261016091204118K7Q2M9XA4D created: 1793608517 task_id: agent-7f3c2a9e4b1d4c6f8a0e5b2d9c1f6a37 step: id: step_f49b9a1af695 type: search source: news query: 2026 Nobel Prize Physiology or Medicine winner announced status: started streamStepCompleted: summary: 'Streaming chunk — step completed (type: step)' value: type: step request_id: 20261016091204118K7Q2M9XA4D created: 1793608517 task_id: agent-7f3c2a9e4b1d4c6f8a0e5b2d9c1f6a37 step: id: step_f49b9a1af695 type: search source: news status: completed ok: true duration_ms: 240 sources_found: 13 streamContent: summary: 'Streaming chunk — content (type: content)' value: type: content request_id: 20261016091204118K7Q2M9XA4D created: 1793608522 task_id: agent-7f3c2a9e4b1d4c6f8a0e5b2d9c1f6a37 choices: - delta: role: assistant content: >- **The 2026 Nobel Prize in Physiology or Medicine was awarded jointly to Karl Deisseroth, Peter Hegemann, and Georg Nagel.**[^1] They were recognized “for their discoveries concerning light-gated ion channels and optogenetics.”[^1] annotations: - type: url_citation url_citation: url: >- https://www.nobelprize.org/prizes/medicine/2026/press-release/ title: >- Press release: Nobel Prize in Physiology or Medicine 2026 - NobelPrize.org start_index: 123 end_index: 127 - type: url_citation url_citation: url: >- https://www.nobelprize.org/prizes/medicine/2026/press-release/ title: >- Press release: Nobel Prize in Physiology or Medicine 2026 - NobelPrize.org start_index: 226 end_index: 230 streamFinish: summary: 'Streaming chunk — finish (type: finish)' value: type: finish request_id: 20261016091204118K7Q2M9XA4D created: 1793608522 task_id: agent-7f3c2a9e4b1d4c6f8a0e5b2d9c1f6a37 streamUsage: summary: 'Streaming chunk — usage (type: usage)' value: type: usage request_id: 20261016091204118K7Q2M9XA4D created: 1793608522 task_id: agent-7f3c2a9e4b1d4c6f8a0e5b2d9c1f6a37 meta: latency: 9376 billed_tier: low cost: 0.05 '400': description: >- Invalid params — Returned when a required parameter is missing or invalid. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: code: 400 msg: >- Invalid params. Param messages must contain at least one message. request_id: req_abc123def456 '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/InsufficientBalance' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' components: schemas: SearchAgentRequest: type: object required: - messages description: Request body for the Search Agent API. properties: messages: type: array description: >- A list of messages comprising the conversation so far. User and assistant messages in chronological order for multi-turn conversations. items: $ref: '#/components/schemas/SearchAgentMessage' previous_task_id: type: string description: The `task_id` of a previous task, to continue its conversation. tier: type: string enum: - auto - low - medium - high default: auto description: >- The task tier. `low`, `medium`, and `high` increase search depth, cost, and time in that order. `auto` is billed by actual usage. response_format: $ref: '#/components/schemas/SearchAgentResponseFormat' stream: type: boolean default: false description: >- Whether to enable streaming output. When `true`, returns chunks incrementally with types: `status`, `step`, `content`, `finish`, and `usage`. SearchAgentResponse: type: object description: A non-streaming Search Agent response. Returned when `stream=false`. required: - request_id - task_id - tier - status - created_at properties: request_id: type: string description: Unique identifier for the request. task_id: type: string description: Unique task id, used to retrieve the result. tier: type: string enum: - auto - low - medium - high description: The tier from the request. status: type: string enum: - queued description: Task state. created_at: type: integer description: Unix timestamp in seconds when the task was created. SearchAgentChunk: type: object description: >- A streaming chunk of a Search Agent response. Returned when `stream=true`. The `type` field indicates the chunk kind: `status`, `step`, `content`, `finish`, `usage`. required: - request_id properties: type: type: string enum: - status - step - content - finish - usage description: The type of this streaming chunk. request_id: type: string description: Unique identifier for the request. created: type: integer description: Unix timestamp (in seconds) of when the chunk was created. task_id: type: string description: Unique task id. status: type: string enum: - queued - running - succeeded - failed - cancelled description: Task state. Present only in `status` chunks. stop_reason: $ref: '#/components/schemas/SearchAgentStopReason' error: $ref: '#/components/schemas/SearchAgentError' step: $ref: '#/components/schemas/SearchAgentStep' choices: type: array description: Incremental choices. Present only in `content` chunks. items: $ref: '#/components/schemas/SearchAgentChunkChoice' meta: $ref: '#/components/schemas/SearchAgentMeta' ErrorResponse: type: object properties: code: type: integer description: Business status code. Non-zero values indicate an error. msg: type: string description: A message describing the error. request_id: type: string description: Unique identifier for the request. required: - code - msg - request_id SearchAgentMessage: type: object required: - role - content description: A single message in the Search Agent request. properties: role: type: string enum: - system - user - assistant description: The role of the message author. content: description: >- The content of the message. Can be a plain string, or an array of text content blocks. oneOf: - type: string - type: array items: $ref: '#/components/schemas/SearchAgentTextContentBlock' SearchAgentResponseFormat: type: object description: Controls the output format. properties: type: type: string enum: - text - json_schema default: text description: The output format type. schema: type: object description: >- Required when `type` is `json_schema`. The JSON Schema definition object. May contain `type`, `properties`, `required`, `additionalProperties`, etc. The top-level `type` must be `object`. SearchAgentStopReason: type: string enum: - schema_satisfied - stopped - budget_reached - time_limit_reached - cancelled - error description: >- Why the task stopped. `schema_satisfied`: completed normally; `stopped`: stopped on request; `budget_reached` / `time_limit_reached`: wrapped up early after reaching an internal budget or time limit; `cancelled`: cancelled; `error`: failed. SearchAgentError: type: object description: >- Failure reason, present when `status` is `failed`. Failed tasks are not billed. properties: code: type: string enum: - AGENT_TIMEOUT - AGENT_FAILED description: >- `AGENT_TIMEOUT`: the task timed out; `AGENT_FAILED`: the task failed for another reason. message: type: string description: A message describing the failure. SearchAgentStep: type: object description: >- A progress step. Present only in `step` chunks. Each step sends one chunk when it starts and one when it completes. properties: id: type: string description: Step id, shared by the chunks of the same step. type: type: string description: Step type, such as `search` or `read`. source: type: string description: Where a `search` step searches, such as `web` or `news`. query: type: string description: The search query. Present when a `search` step starts. url: type: string description: The URL of the page. Present when a `read` step starts. status: type: string description: 'Step state: `started` or `completed`.' ok: type: boolean description: Whether the step succeeded. Present when the step completes. duration_ms: type: integer description: Step time in milliseconds. Present when the step completes. sources_found: type: integer description: Number of sources the step found. Present when the step completes. SearchAgentChunkChoice: type: object description: A single choice in a Search Agent streaming chunk. properties: delta: type: object description: Incremental content in a Search Agent streaming chunk. properties: role: type: string enum: - assistant description: The role. Included in the first `content` chunk. content: type: string description: >- Incremental answer text. Concatenate across `content` chunks to build the final answer. annotations: type: array description: >- Citation annotations added in this chunk. `start_index` and `end_index` are positions in the full answer. items: $ref: '#/components/schemas/SearchAgentAnnotation' SearchAgentMeta: type: object description: Metadata for the Search Agent response. properties: latency: type: integer description: Total request latency in milliseconds. billed_tier: type: string enum: - auto - low - medium - high description: The tier actually billed for this request. cost: type: number description: Amount charged for this task in USD. SearchAgentTextContentBlock: type: object required: - type description: A text content block. properties: type: type: string enum: - text description: The block type. Always `text` for Search Agent. text: type: string description: The text content. SearchAgentAnnotation: type: object description: A citation annotation. properties: type: type: string enum: - url_citation description: The annotation type. url_citation: type: object properties: url: type: string description: The URL of the cited source. title: type: string description: The title of the cited source. start_index: type: integer description: Start position of the cited span in `content`. end_index: type: integer description: End position of the cited span in `content`. responses: Unauthorized: description: Invalid API Key — Returned when the API key is missing or invalid. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: code: 401 msg: Invalid API Key request_id: req_abc123def456 InsufficientBalance: description: >- Insufficient balance in account — Returned when the account balance is insufficient to complete the request. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: code: 403 msg: Insufficient balance in account request_id: req_abc123def456 RateLimited: description: >- Exceeding the rate limit — Returned when the request exceeds the configured rate limit. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: code: 429 msg: Exceeding the rate limit request_id: req_abc123def456 InternalError: description: Internal error — Returned when an unexpected server-side error occurs. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: code: 500 msg: Internal error request_id: req_abc123def456 securitySchemes: bearerAuth: type: http scheme: bearer description: >- Bearer token used for request authentication. Alternatively, you can send the API key in the `x-api-key` header. Note: A payment method is required to use the API. apiKeyAuth: type: apiKey in: header name: x-api-key description: >- API key used for request authentication. Alternatively, you can send the key as a Bearer token in the `Authorization` header. Note: A payment method is required to use the API. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.