> ## Documentation Index > Fetch the complete documentation index at: https://developers.telnyx.com/llms.txt > Use this file to discover all available pages before exploring further. # Web search > Performs a real-time web search and returns structured, LLM-ready JSON results with titles, URLs, descriptions, and snippets. Supports filtering by domain, country, safe search, freshness, and live crawl. **Note:** `include_domains` and `exclude_domains` cannot be used in the same request. Use one or the other. ## OpenAPI ````yaml /openapi/source/external/web-search/web-search.json post /web_search openapi: 3.1.0 info: version: 1.0.0 title: Telnyx API x-latency-category: interactive x-endpoint-cost: light description: >- Real-time web search, page content retrieval, and deep research with citations, exposed through the Telnyx API Gateway and powered by the `telnyx-agent-web-search` service. ## Authentication All endpoints require a Telnyx API key sent as a Bearer token in the `Authorization` header. The API Gateway validates the key and forwards the verified identity to the backend service as `Telnyx-Auth-Rev2`. ## Rate Limits Default rate limit: 60 requests per minute per API key. ## Error Responses Errors follow the format `{ "error": { "message": string, "details": object } }`. contact: email: support@telnyx.com servers: - url: https://api.telnyx.com/v2 description: Telnyx API v2 security: - bearerAuth: [] tags: - name: Web Search description: Real-time web search returning structured, LLM-ready JSON results. - name: Contents description: Page content retrieval for URLs. - name: Research description: Deep research with citations and async task polling. paths: /web_search: post: tags: - Web Search summary: Web search description: >- Performs a real-time web search and returns structured, LLM-ready JSON results with titles, URLs, descriptions, and snippets. Supports filtering by domain, country, safe search, freshness, and live crawl. **Note:** `include_domains` and `exclude_domains` cannot be used in the same request. Use one or the other. operationId: CreateWebSearch requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/WebSearchRequest' example: query: latest AI agent frameworks count: 10 country: US safesearch: moderate freshness: week include_domains: - arxiv.org - github.com livecrawl: false responses: '200': description: Successful search response. content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/WebSearchResponse' example: data: results: web: - url: https://example.com/article title: Top AI Agent Frameworks in 2026 description: >- A comprehensive guide to the latest AI agent frameworks... snippets: - >- LangGraph is a framework for building stateful, multi-actor agents... thumbnail_url: https://example.com/thumb.jpg favicon_url: >- https://cdn.telnyx.com/favicon?domain=example.com&size=128 news: [] '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '500': $ref: '#/components/responses/InternalServerError' '502': $ref: '#/components/responses/ProviderError' '504': $ref: '#/components/responses/ProviderTimeout' x-codeSamples: - lang: JavaScript source: |- import Telnyx from 'telnyx'; const client = new Telnyx({ apiKey: process.env['TELNYX_API_KEY'], // This is the default and can be omitted }); const response = await client.webSearch.create({ query: 'latest AI agent frameworks', }); console.log(response.data); - lang: Python source: | import os from telnyx import Telnyx client = Telnyx( api_key=os.environ.get("TELNYX_API_KEY"), # This is the default and can be omitted ) response = client.web_search.create( query="latest AI agent frameworks", ) print(response.data) - lang: Go source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/team-telnyx/telnyx-go\"\n\t\"github.com/team-telnyx/telnyx-go/option\"\n)\n\nfunc main() {\n\tclient := telnyx.NewClient(\n\t\toption.WithAPIKey(\"My API Key\"),\n\t)\n\twebSearch, err := client.WebSearch.New(\n\t\tcontext.TODO(),\n\t\ttelnyx.WebSearchNewParams{\n\t\t\tQuery: \"latest AI agent frameworks\",\n\t\t},\n\t)\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", webSearch.Data)\n}\n" - lang: Java source: |- package com.telnyx.sdk.example; import com.telnyx.sdk.client.TelnyxClient; import com.telnyx.sdk.client.okhttp.TelnyxOkHttpClient; import com.telnyx.sdk.models.webSearch.WebSearchCreateParams; public final class Main { private Main() {} public static void main(String[] args) { TelnyxClient client = TelnyxOkHttpClient.fromEnv(); WebSearchCreateParams params = WebSearchCreateParams.builder() .query("latest AI agent frameworks") .build(); var response = client.webSearch().create(params); } } - lang: Ruby source: >- require "telnyx" telnyx = Telnyx::Client.new(api_key: "My API Key") response = telnyx.web_search.create(query: "latest AI agent frameworks") puts(response) - lang: PHP source: >- webSearch->create( query: 'latest AI agent frameworks', ); var_dump($response); } catch (APIException $e) { echo $e->getMessage(); } - lang: CLI source: |- telnyx web-search create \ --api-key 'My API Key' \ --query 'latest AI agent frameworks' components: schemas: WebSearchRequest: type: object required: - query properties: query: type: string minLength: 1 maxLength: 2000 description: The search query text. example: latest AI agent frameworks count: type: integer minimum: 1 maximum: 100 description: Number of results to return (1-100). example: 10 country: type: string minLength: 2 maxLength: 2 description: Two-letter country code (ISO 3166-1 alpha-2) to bias results. example: US safesearch: type: string enum: - 'off' - moderate - strict description: Safe search filter level. example: moderate freshness: type: string maxLength: 20 description: >- Time-based filter for results. Common values: `day`, `week`, `month`, `year`. example: week include_domains: type: array items: type: string maxItems: 50 description: >- Restrict results to these domains (bare hostnames, e.g. `arxiv.org`). example: - arxiv.org - github.com exclude_domains: type: array items: type: string maxItems: 50 description: >- Exclude results from these domains (bare hostnames, e.g. `pinterest.com`). example: - pinterest.com livecrawl: type: boolean description: >- When true, the provider crawls pages in real-time for fresh content. The boolean is translated to the provider's internal enum internally; callers always pass `true` or `false`. example: false WebSearchResponse: type: object properties: results: type: object required: - web properties: web: type: array items: $ref: '#/components/schemas/WebSearchResult' description: Web search results. news: type: array items: $ref: '#/components/schemas/WebSearchResult' description: >- News search results. Present only when the query surfaces news results. WebSearchResult: type: object required: - url - title - description - snippets properties: url: type: string format: uri description: Result URL. title: type: string description: Result title. description: type: string description: Short description or excerpt. snippets: type: array items: type: string description: Relevant text snippets from the page. thumbnail_url: type: string format: uri description: Thumbnail image URL (if available). favicon_url: type: string format: uri description: Favicon URL (if available). WebSearchError: type: object properties: error: type: object required: - message properties: message: type: string description: Human-readable error message. details: type: object additionalProperties: true description: Additional error details (e.g. validation field errors). GatewayError: type: object description: >- Standard Telnyx JSON:API error envelope returned by the API Gateway for authentication failures (401). required: - errors properties: errors: type: array items: type: object required: - code - title properties: code: type: string description: Telnyx error code. title: type: string description: Error title. detail: type: string description: Human-readable error detail. source: type: object properties: pointer: type: string meta: type: object properties: url: type: string format: uri responses: BadRequest: description: Invalid request — validation error or invalid parameters. content: application/json: schema: $ref: '#/components/schemas/WebSearchError' example: error: message: Validation error details: {} Unauthorized: description: >- Unauthorized — missing or invalid API key. The API Gateway returns this response before the request reaches the backend service. The error format follows the standard Telnyx JSON:API error envelope with `errors[]`, not the backend-level `WebSearchError` shape. content: application/json: schema: $ref: '#/components/schemas/GatewayError' example: errors: - code: '10009' title: Authentication failed detail: Could not find any usable credentials in the request. meta: url: https://developers.telnyx.com/docs/overview/errors/10009 InternalServerError: description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/WebSearchError' example: error: message: Internal server error ProviderError: description: The upstream search provider returned an error. content: application/json: schema: $ref: '#/components/schemas/WebSearchError' example: error: message: Provider request failed ProviderTimeout: description: The upstream search provider timed out. content: application/json: schema: $ref: '#/components/schemas/WebSearchError' example: error: message: Provider request timed out securitySchemes: bearerAuth: type: http scheme: bearer description: Telnyx API key ````