# Telnyx Agent Tools: Web Search — Full Documentation
> Complete page content for Web Search (Agent Tools section) of the Telnyx developer docs (https://developers.telnyx.com).
> This file: https://developers.telnyx.com/docs/development/llms/agent-tools-web-search-llms-full-txt.md · Root index: https://developers.telnyx.com/llms.txt

## Web Search

### Overview

> Source: https://developers.telnyx.com/docs/web-search.md

Web Search gives your application live access to the web through one API: run real-time searches with structured, LLM-ready results, retrieve clean page content, or hand off an entire research question and get back a synthesized answer with citations.

It is built as grounding for AI agents -- every response is structured JSON ready to feed a model as tool output.

## What You Can Do

| Capability | Endpoint | Returns |
| --- | --- | --- |
| [Web Search](/docs/web-search/web-search) | `POST /web_search` | Ranked results with titles, descriptions, and snippets |
| [Content Retrieval](/docs/web-search/contents) | `POST /web_search/contents` | Clean HTML or Markdown for up to 20 URLs per request |
| [Research](/docs/web-search/research) | `POST /web_search/research` | A synthesized answer with citations, synchronous or background |

## Next Steps

    First search to synthesized answer in a few minutes.
    Domain filters, freshness, and live crawling.
    Formats, caching, and per-URL behavior.
    Synchronous vs background mode, polling, and the task lifecycle.

---

### Get Started

> Source: https://developers.telnyx.com/docs/web-search/getting-started.md

Search the web for live results, pull clean content from a result URL, then let the research endpoint do both for you and synthesize an answer with citations. Every step is a copy-paste request -- set `TELNYX_API_KEY` to a key from the [portal](https://portal.telnyx.com/#/api-keys) and they work as-is.

```bash
curl -X POST https://api.telnyx.com/v2/web_search \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "telnyx voice api",
    "count": 2
  }'
```

```json
{
  "data": {
    "results": {
      "web": [
        {
          "url": "https://telnyx.com/products/voice-api",
          "title": "Voice API on the Carrier Network | Telnyx",
          "description": "Programmable voice on infrastructure Telnyx owns. Call control, transfer, record, monitor at the carrier layer.",
          "snippets": ["Deploy seamless communication experiences with developer-friendly APIs..."],
          "thumbnail_url": "https://telnyx.com/static/thumbnail/voice-api.png"
        }
      ]
    }
  }
}
```

Results come back ranked and structured -- `title`, `url`, `description`, `snippets` -- ready to hand to a model. Narrow them with domain, country, freshness, and safe-search filters; see [Web Search](/docs/web-search/web-search) for how the filters behave.

Search gives you snippets; content retrieval gives you the page. Ask for `markdown` and feed it straight to a model:

```bash
curl -X POST https://api.telnyx.com/v2/web_search/contents \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": ["https://en.wikipedia.org/wiki/Telnyx"],
    "formats": ["markdown"]
  }'
```

```json
{
  "data": {
    "results": [
      {
        "url": "https://en.wikipedia.org/wiki/Telnyx",
        "title": "Telnyx - Wikipedia",
        "markdown": "[Jump to content](https://en.wikipedia.org/wiki/Telnyx#bodyContent)\n\nFrom Wikipedia, the free encyclopedia..."
      }
    ]
  }
}
```

One request handles up to 20 URLs. See [Content Retrieval](/docs/web-search/contents) for formats and per-URL behavior.

For a whole question, skip the orchestration: research runs the searches, reads the sources, and returns a synthesized answer with citations.

```bash
curl -X POST https://api.telnyx.com/v2/web_search/research \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What is SIP trunking and how does it differ from PSTN?",
    "research_effort": "lite"
  }'
```

```json
{
  "data": {
    "answer": "SIP trunking is a modern technology that uses the internet to transmit voice, video, and data packets, replacing traditional physical phone lines [[1, 2, 3]]...",
    "citations": [
      {
        "url": "https://www.zayo.com/resources/what-is-sip-trunking-sip-trunking-defined/",
        "title": "What is SIP Trunking? | SIP Trunking Defined - Zayo",
        "snippet": "Maintaining seamless communication..."
      }
    ]
  }
}
```

Synchronous requests block until the answer is ready. For long-running research, add `"background": true` to get a `task_id` back immediately, then poll until `status` is `completed`:

```bash
curl https://api.telnyx.com/v2/web_search/research/{task_id} \
  -H "Authorization: Bearer $TELNYX_API_KEY"
```

See [Research](/docs/web-search/research) for sync vs background and the task lifecycle.

Each response is tool output: declare search, retrieval, or research as function tools, run them when the model asks, and feed the JSON back. The `[[1, 2, 3]]` markers in research answers index into `citations`, so your agent can quote sources directly.

## Next Steps

    Domain filters, freshness, and live crawling.
    Formats, caching, and per-URL behavior.
    Synchronous vs background mode and polling.

---

## Features

### Web Search

> Source: https://developers.telnyx.com/docs/web-search/web-search.md

`POST /web_search` returns ranked, LLM-ready results -- `title`, `url`, `description`, and `snippets` per result. Every parameter and schema is in the API Reference; this page covers behavior.

## Domain Filters

`include_domains` and `exclude_domains` take bare hostnames (`arxiv.org`, up to 50) and are mutually exclusive -- sending both is rejected.

## Freshness

`freshness` is a free-form window of up to 20 characters, not an enum. `day`, `week`, `month`, and `year` are the reliable values; other values pass through to the search index, and unrecognized ones return unfiltered results rather than an error.

## Live Crawling

`livecrawl: true` fetches pages at query time for fresh content -- slower, and more likely to hit a `504`. If a live-crawled search times out, retry with `livecrawl: false`.

## News Results

`data.results.news` appears only when the query surfaces news. Expect the key to be absent -- not an empty array -- for most queries.

---

### Content Retrieval

> Source: https://developers.telnyx.com/docs/web-search/contents.md

`POST /web_search/contents` turns up to 20 URLs into clean, model-ready content in one request. Every parameter and schema is in the API Reference; this page covers behavior.

## Formats Are Best-Effort Per URL

Every result carries `url`, and `title` whenever the page has one. Beyond that, which fields come back varies by URL and cache state:

- With `formats` omitted, `html` and `metadata` are the defaults.
- Requesting `markdown` does not suppress `html` — a freshly crawled page may return both, while cached content returns exactly the requested formats. If you only need `markdown`, ignore the `html` field in the response.
- `metadata.site_name` is frequently an empty string; rely on `title` instead.

## Caching

Content is served from a crawl cache when possible: cached responses return in well under a second, fresh crawls take one to a few seconds per URL. `max_age` bounds how old a cached copy may be, and `crawl_timeout` caps each URL's fetch time.

---

### Research

> Source: https://developers.telnyx.com/docs/web-search/research.md

`POST /web_search/research` hands a question to a pipeline that searches, reads sources, and synthesizes a cited answer. Every parameter and schema is in the API Reference; this page covers behavior.

## Synchronous or Background

Synchronous requests (the default) block until the answer is ready -- tens of seconds in practice, up to 120 depending on `research_effort`. The response is just `answer` and `citations`.

Use `"background": true` when you don't want to hold a connection open: the request returns a `task_id` immediately, and `GET /web_search/research/{task_id}` polls the result.

## Task Lifecycle

Tasks move `pending` → `running` → `completed` or `failed`. Poll responses always include `error` -- it stays `null` unless the task actually failed, so branch on `status`, not on the key's presence. `answer` and `citations` join the payload on completion.

Task IDs are ephemeral: unknown, malformed, expired, and already-purged IDs all return the same `404` with `{ "error": { "message": "Task not found" } }`. Treat a 404 as "start a new research request", not as a retryable error.

## Citation Markers

Answers cite inline with bracketed markers -- `SIP trunking uses the internet to transmit voice [[1, 2, 3]]` -- which are 1-based indexes into the `citations` array. Agents can use them to attribute each claim to its source; `max_sources` caps how many sources the pipeline draws from.

---

## API Reference (Web Search)

### Web Search

- [Web search](https://developers.telnyx.com/api-reference/web-search/web-search.md): Performs a real-time web search and returns structured, LLM-ready JSON results with titles, URLs, descriptions, and snippets. Supports filtering by domain, cou…

### Contents

- [Retrieve page contents](https://developers.telnyx.com/api-reference/contents/retrieve-page-contents.md): Retrieves clean HTML or Markdown content from a list of URLs. Supports up to 20 URLs per request (public API limit). Specify which formats to return: `html`, `…

### Research

- [Start research task](https://developers.telnyx.com/api-reference/research/start-research-task.md): Starts a deep research task that runs multiple searches, reads sources, and synthesizes an answer with citations.
- [Get research task status](https://developers.telnyx.com/api-reference/research/get-research-task-status.md): Polls the status of a previously started asynchronous research task. When the status is `completed`, the response includes the answer and citations. When the s…