--- title: "Search the web with a selected provider" method: POST path: "/v3/websearch" tags: ["Web Search"] --- # Search the web with a selected provider `POST /v3/websearch` ## Request - Base URL: `https://my.orq.ai` - URL: `https://my.orq.ai/v3/websearch` - Auth: HTTP bearer Search with Exa, Ceramic, Linkup, Tavily, Serper, OpenAI, Perplexity, or DeepSeek and return page URLs, titles, and descriptions in one response format. Authenticate with an API key that grants **websearch.execute** and send **Content-Type: application/json**. ### Provider and credentials Each request uses the selected provider. Exa uses **auto** search, Linkup uses **standard** depth, Tavily uses **basic** depth, and Perplexity and DeepSeek use their standard Search APIs. DeepSeek accepts queries of at most 128 characters. OpenAI runs one forced **web_search** tool call on gpt-5.6-luna through the Responses API and returns the raw search results. Credentials are selected from the authenticated workspace. A configured provider integration takes precedence over ORQ-managed credentials: the default integration is used, or the first configured integration if no default is set. Configure BYOK in the workspace integrations settings. Invalid integration credentials cause an error. ### Billing Managed searches use the same credits as the **AI Gateway** and charge the provider cost plus **US$0.001 per search** (US$1 per 1,000 searches). BYOK searches consume no ORQ credits and add no ORQ markup; the provider bills the integration owner directly. Exa's published auto rate is **US$7 per 1,000 requests** for up to 10 results, or **US$8 per 1,000** including the ORQ markup. Exa charges use the actual cost reported by the provider. Perplexity's published Search API rate is **US$5 per 1,000 requests** and DeepSeek's is **US$0.75 per 1,000 requests**. OpenAI web search costs **US$10 per 1,000 tool calls** plus the gpt-5.6-luna tokens of the Responses call, computed from the usage reported by OpenAI, so each search is typically US$0.012 to US$0.015 before the ORQ markup. A successful managed search is billable even if an output guardrail or output redaction failure prevents the results from being returned. ### Policies and observability PII Redaction is the only supported request plugin. Workspace PII settings and matching guardrail rules also apply. Query redaction runs before input guardrails and the provider call; result redaction runs before output guardrails and the response. Search spans and metrics record the provider, latency, result count, and cost. Use the **x-orq-trace-id** response header to find the trace. ## Request body - object - `identity` object: Customer or end-user identity for attributing this search and its usage. - `id` string, required: Customer or end-user identifier used consistently across API requests. - `limit` integer: Maximum number of results to return, from 1 to 10. Defaults to 10. The provider may return fewer results. - `plugins` object[]: Optional PII Redaction configuration. At most one plugin is accepted, with id pii_redaction. Workspace and matching rule requirements still apply when this field is omitted. - `entities` string[], nullable: Entity types to redact, using names supported by the PII detector. Used alone, this is an allowlist; combined with regions, both sets of detectors apply. - `entity_thresholds` object: Per-entity confidence cutoffs from 0 to 1, applied in addition to threshold. Each key must also appear in entities. - `id` 'pii_redaction', required: Plugin identifier. Must be pii_redaction. - `language` string: Language used by the PII detector. Omitting the field defaults to auto, which detects the language per request; supported languages depend on the detector capabilities. - `on_failure` string: Behavior when the PII detector fails: block rejects the request (default); passthrough continues with the original text. Workspace and rule requirements can enforce blocking. - `regions` string[], nullable: Country codes that select regional PII detectors. Use ["all"] on its own for all regions. Omitting both regions and entities enables all regions. - `threshold` number, double: Minimum detection confidence from 0 to 1. Omit to use the detector's default threshold. - `provider` 'exa' | 'ceramic' | 'linkup' | 'tavily' | 'serper' | 'openai' | 'perplexity' | 'deepseek', required: Provider to run this search. Exa uses auto, Linkup uses standard depth, Tavily uses basic depth, and OpenAI runs one web_search tool call on gpt-5.6-luna. Workspace credentials are selected automatically for this provider. - `query` string, required: Search text. Must not be blank or exceed 10,000 characters. Ceramic accepts at most 50 words and DeepSeek at most 128 characters. ## Response `200` Search completed. Results may be empty or fewer than the requested limit. - object - `items` object[], required: Results in the provider's order, after any required PII redaction. Empty when no results are found. - `description` string, required: Provider-supplied excerpt or description. May be empty. - `title` string, required: Page title. May be empty if the provider supplies no title. - `url` string, required: Page URL returned by the provider. PII redaction can replace sensitive parts of the URL. - `metadata` object, required: Details about this search request. - `latencyMs` integer, required: Elapsed search processing time in milliseconds, including applied policies. - `provider` 'exa' | 'ceramic' | 'linkup' | 'tavily' | 'serper' | 'openai' | 'perplexity' | 'deepseek', required: Provider that executed the search. - `query` string, required: Query sent to the provider after any required PII redaction. - `requestId` string, required: ORQ-generated identifier for this search request. Distinct from the trace ID in the response headers. ## Other responses - `400`: Invalid request, unusable workspace integration, or a blocking guardrail. Check the request fields and workspace integration settings. - `401`: Missing or invalid API key. Send a valid API key in the Authorization header. - `402`: Managed search requires a positive ORQ credit balance. Add credits before retrying. BYOK does not require ORQ credits. - `403`: The API key lacks websearch.execute permission. - `415`: Unsupported or missing Content-Type. Send application/json; an optional charset parameter is accepted. - `422`: A configured guardrail evaluator could not complete its evaluation. - `429`: A workspace or provider rate limit, or a matching budget, was reached. Wait before retrying or raise the budget. - `500`: Unexpected gateway error. Include the trace ID, if available, when reporting the failure. - `502`: The search provider, PII detector, or guardrail service failed. Invalid upstream credentials can also produce this response. - `503`: The gateway could not load workspace integrations. Retry when the credential store is available. - `504`: The provider request timed out or was cancelled. ## Changes > 554 revisions in range; 71 not diffed. - **2026-10-18** `5a692f00e432`: 1 warning, 1 info - added the new `deepseek` enum value to the `metadata/provider` response property for the response status `200` - added the new `deepseek` enum value to the request property `provider` - **2026-10-06** `41cfb3cdd993`: 2 warning, 2 info - added the new `openai` enum value to the `metadata/provider` response property for the response status `200` - added the new `perplexity` enum value to the `metadata/provider` response property for the response status `200` - added the new `openai` enum value to the request property `provider` - added the new `perplexity` enum value to the request property `provider` - **2026-10-05** `b8af63cacd70`: 1 info - endpoint added [Operation history](https://skmtc.dev/orq-ai/apis/orq-ai-api/changes/v3/websearch/post.md) --- [API](https://skmtc.dev/orq-ai/apis/orq-ai-api.md) - [All operations](https://skmtc.dev/orq-ai/apis/orq-ai-api/llms.txt) - [OpenAPI document](https://skmtc.dev/orq-ai/apis/orq-ai-api/revisions/928a71e92252?raw)