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

# Web search

`POST /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.

## Request body

- WebSearchRequest
  - `count` integer — Number of results to return (1-100).
  - `country` string — Two-letter country code (ISO 3166-1 alpha-2) to bias results.
  - `exclude_domains` string[] — Exclude results from these domains (bare hostnames, e.g. `pinterest.com`).
  - `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`).
  - `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`.
  - `query` string, required — The search query text.
  - `safesearch` 'off' | 'moderate' | 'strict' — Safe search filter level.

## Response `200`

Successful search response.

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

## 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.

---

[API](https://skmtc.net/team-telnyx/apis/telnyx-api-2.md) · [All operations](https://skmtc.net/team-telnyx/apis/telnyx-api-2/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/team-telnyx/telnyx-api-2/revisions/3fdc16374d70/schema)