> ## 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 > Searches ranked web results for a given query, with optional filters, highlights, and full content. ## OpenAPI ````yaml /api-reference/openapi.json post /search openapi: 3.1.0 info: title: Octen API description: >- Octen API provides Search, Extract, Embeddings, VL Embeddings, Web Chat, Broad Search, and Deep Research services. The Search API searches ranked web results with optional filters, highlights, and full content. The Extract API extracts clean markdown 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 (text, images, videos) into vector representations. The Web Chat API provides LLM chat completions with search augmentation. The Broad Search API automatically 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 web searches, builds a report brief with evidence, and streams a final long-form report. version: 1.0.0 servers: - url: https://api.octen.ai security: - apiKeyAuth: [] paths: /search: post: summary: Search description: >- Searches ranked web results for a given query, with optional filters, highlights, and full content. operationId: search requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SearchRequest' examples: basic: summary: Basic Search value: query: >- What record did Kendrick Lamar break at the 2026 Grammy Awards? count: 5 domainFiltering: summary: Domain Filtering + Time Range + Highlights value: query: summary judgment count: 10 time_basis: published start_time: '2024-01-01T00:00:00+08:00' end_time: '2025-01-01T00:00:00+08:00' include_domains: - uscourts.gov highlight: enable: true max_tokens: 300 full_content: enable: false format: text fullContent: summary: Full Content Enabled value: query: latest WHO guidance on influenza vaccination count: 5 full_content: enable: true max_tokens: 1000 responses: '200': description: Successful search response content: application/json: schema: $ref: '#/components/schemas/SearchResponse' example: code: 0 msg: success request_id: req_abc123def456 data: query: latest WHO guidance on influenza vaccination results: - title: Influenza (Seasonal) - World Health Organization (WHO) url: >- https://www.who.int/news-room/fact-sheets/detail/influenza-(seasonal) highlight: >- WHO recommends annual vaccination for high-risk groups ... Seasonal influenza vaccination policies vary by region... authors: World Health Organization time_published: '2024-10-15T00:00:00Z' time_last_crawled: '2026-01-20T02:12:34Z' favicon: https://www.who.int/favicon.ico cover_image: url: >- https://www.who.int/images/default-source/influenza/seasonal-influenza-cover.jpg description: Seasonal influenza vaccination images: - url: >- https://www.who.int/images/default-source/influenza/influenza-vaccine-vial.jpg description: A vial of seasonal influenza vaccine. videos: - url: https://www.who.int/videos/influenza-explainer.m3u8 description: WHO explainer on seasonal influenza. meta: usage: num_search_queries: 1 full_content_tokens: 0 latency: 237 warning: null '400': description: >- Missing parameter query — Returned when a required parameter is missing. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: code: 400 msg: Missing parameter query '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/InsufficientBalance' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' components: schemas: SearchRequest: type: object required: - query properties: query: type: string maxLength: 500 description: The search query. topic: type: string enum: - general - news default: general description: >- Search category. Use `general` for broad web search, or `news` for news-focused results. count: type: integer default: 5 minimum: 1 maximum: 100 description: Number of results to return. include_domains: type: array items: type: string maxLength: 30 maxItems: 1000 description: A list of domains to specifically include in the search results. example: - octen.ai - wikipedia.org exclude_domains: type: array items: type: string maxLength: 30 maxItems: 150 description: A list of domains to specifically exclude from the search results. example: - spam.com - ads.example.net include_text: type: array items: type: string maxLength: 30 maxItems: 5 description: Strings that must appear in the result page text. exclude_text: type: array items: type: string maxLength: 30 maxItems: 5 description: Strings that must not appear in the result page text. time_basis: type: string enum: - auto - published - crawled default: auto description: >- Determines which time field is used for time filtering. `published` uses time_published; `crawled` uses time_last_crawled. time_range: type: string enum: - day - week - month - year - d - w - m - 'y' description: >- Relative time window counting back from the current time based on `time_basis`. Mutually exclusive with `start_time`/`end_time` — if both are provided, `start_time`/`end_time` take precedence. start_time: type: string format: date-time description: >- Start time for filtering results (based on time_basis). ISO 8601 format. example: '2025-01-01T00:00:00+08:00' end_time: type: string format: date-time description: >- End time for filtering results (based on time_basis). ISO 8601 format. example: '2025-01-01T00:00:00+08:00' highlight: $ref: '#/components/schemas/HighlightOptions' format: type: string enum: - markdown - text default: text description: Controls the formatting of highlight outputs. safesearch: type: string enum: - 'off' - strict default: strict description: >- Controls filtering of explicit/adult content. `off` disables filtering; `strict` drops all adult content. full_content: $ref: '#/components/schemas/FullContentOptions' include_images: type: boolean default: false description: >- Whether to include images (cover_image and in-body images) in each result. include_videos: type: boolean default: false description: Whether to include videos in each result. SearchResponse: type: object properties: code: type: integer description: Business status code. 0 indicates success. msg: type: string description: A human-readable message describing the result. request_id: type: string description: The unique identifier for this request. data: $ref: '#/components/schemas/SearchData' meta: $ref: '#/components/schemas/SearchMeta' ErrorResponse: type: object properties: code: type: integer description: Business status code. Non-zero values indicate an error. msg: type: string description: A human-readable message describing the error. required: - code - msg HighlightOptions: type: object description: Controls highlight extraction from result pages. properties: enable: type: boolean default: true description: If true, returns query-relevant highlight in each result. max_tokens: type: integer default: 512 minimum: 100 maximum: 20000 description: Max tokens returned per highlight. FullContentOptions: type: object description: Controls whether to return the full raw content of each result page. properties: enable: type: boolean default: false description: If true, returns full_content for each result. max_tokens: type: integer default: 2048 minimum: 100 maximum: 100000 description: Maximum tokens of full content included per result. SearchData: type: object description: The main response payload. properties: query: type: string description: The original query. results: type: array description: A list of search results. items: $ref: '#/components/schemas/SearchResult' SearchMeta: type: object description: Additional metadata for the search request. properties: usage: $ref: '#/components/schemas/SearchUsage' latency: type: number description: Response time in milliseconds. warning: type: string nullable: true description: Warning message, if any. SearchResult: type: object description: A single search result. properties: title: type: string description: The title of the result page. url: type: string description: The URL of the result page. highlight: type: string description: >- Query-relevant highlight snippets. Returned only if highlight.enable is true. full_content: type: string description: Full raw page content. Returned only if full_content.enable is true. authors: type: string description: Website name or author. time_published: type: string format: date-time description: Publish time in ISO 8601. time_last_crawled: type: string format: date-time description: Last crawl time in ISO 8601. favicon: type: string description: The favicon URL of the result site. cover_image: type: object description: >- The page cover image. Returned only when `include_images` is true and the page has a cover image. properties: url: type: string description: The cover image URL. description: type: string description: Text description of the cover image. May be empty. images: type: array description: >- In-body images of the page, in order of appearance. Returned only when `include_images` is true. items: type: object properties: url: type: string description: The image URL. description: type: string description: Text description of the image. May be empty. videos: type: array description: >- In-body videos of the page, in order of appearance. Returned only when `include_videos` is true. items: type: object properties: url: type: string description: The video URL. description: type: string description: Text description of the video. May be empty. SearchUsage: type: object description: Usage information for the search request. properties: num_search_queries: type: integer description: Number of search queries executed. full_content_tokens: type: integer description: Tokens returned in full_content across all results. 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 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 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 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 securitySchemes: apiKeyAuth: type: apiKey in: header name: x-api-key description: >- API key used for request authentication. Obtain an API key before using the API. Note: A payment method is required to use the API. ````