---
title: "Web search"
method: POST
path: "/web_search"
tags: ["Web Search"]
---

# Web search

`POST /web_search`

## Request

- Base URL: `https://api.telnyx.com/v2`
- URL: `https://api.telnyx.com/v2/web_search`
- Auth: HTTP bearer

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.

## Request body

- WebSearchRequest
  - `query` string, required: The search query text.
  - `count` integer: Number of results to return (1-100).
  - `country` string: Two-letter country code (ISO 3166-1 alpha-2) to bias results.
  - `safesearch` 'off' | 'moderate' | 'strict': Safe search filter level.
  - `freshness` string: Time-based filter for results. Common values: `day`, `week`, `month`, `year`.
  - `include_domains` string[]: Restrict results to these domains (bare hostnames, e.g. `arxiv.org`).
  - `exclude_domains` string[]: Exclude results from these domains (bare hostnames, e.g. `pinterest.com`).
  - `livecrawl` boolean: 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`.

## Response `200`

Successful search response.

- object
  - `data` WebSearchResponse
    - `results` object
      - `web` WebSearchResult[], required: Web search results.
        - `url` string, uri, required: Result URL.
        - `title` string, required: Result title.
        - `description` string, required: Short description or excerpt.
        - `snippets` string[], required: Relevant text snippets from the page.
        - `thumbnail_url` string, uri: Thumbnail image URL (if available).
        - `favicon_url` string, uri: Favicon URL (if available).
      - `news` WebSearchResult[]: News search results. Present only when the query surfaces news results.
        - `url` string, uri, required: Result URL.
        - `title` string, required: Result title.
        - `description` string, required: Short description or excerpt.
        - `snippets` string[], required: Relevant text snippets from the page.
        - `thumbnail_url` string, uri: Thumbnail image URL (if available).
        - `favicon_url` string, uri: Favicon URL (if available).

## Other responses

- `400`: Invalid request — validation error or invalid parameters.
- `401`: 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.
- `500`: Internal server error.
- `502`: The upstream search provider returned an error.
- `504`: The upstream search provider timed out.

## Changes

- **2026-10-15** `a72569d69430`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/team-telnyx/apis/telnyx-api/changes/web_search/post.md)

---

[API](https://skmtc.dev/team-telnyx/apis/telnyx-api.md) - [All operations](https://skmtc.dev/team-telnyx/apis/telnyx-api/llms.txt) - [OpenAPI document](https://skmtc.dev/team-telnyx/apis/telnyx-api/revisions/0f17b8167873?raw)