> ## Documentation Index
> Fetch the complete documentation index at: https://docs.archal.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Tavily

> Search, extract, crawl, map, research, usage, and API key operations.

Tavily is included in Archal's environment catalog. Use it in a sandbox for search, extract, crawl, map, research, usage, and API key operations.

| | |
| - | - |
| Environment ID | `tavily` |
| Transport | REST |
| State | JSON |
| Contract | `archal.environment-state.tavily` version `1` |
| Channel | Public |
| Curated samples | 5 |

Public means the environment is released and startable. It still describes a bounded provider surface, not a promise that every upstream operation exists.

## Compatibility boundary

**Local catalog validation:** All five published samples passed. Checks cover the state contract, relationships, artifact hash, secret scan, and size limit.

> [!NOTE]
>
> Local catalog validation is not hosted proof. Archal checks current certification, reset, and isolation evidence before admitting new sandboxes. Use the authenticated environment catalog for live availability.

* No fresh web access and no guarantee for replay-backed search/crawl/extract/map inputs outside evidence.

## Curated starting states

List the five samples with `archal sample list tavily`. Each sample is a versioned starting state with a representative read, mutation, expected diff, reset expectation, and verified artifact hash.

> [accordion] Tavily seeded search baseline
>
> Run one deterministic connector-research search from loaded state, then create a new asynchronous research request.
>
> **Sample ID:** `tavily.seeded-search-baseline.v1`
>
> **Category:** `minimal`
>
> **Starting state:** 2 records across `researchRequests`: 1, `searchResults`: 1
>
> **Supported surface:** Stateful deterministic research requests and seeded search-result lookups.
>
> **Required capabilities:** `state.read`, `state.load`, `state.reset`, `rest.research`
>
> **First read:** `POST /search`. Expected result: HTTP 200.
>
> **First-read input**
>
> ```json theme={null}
> {
>   "include_answer": true,
>   "max_results": 5,
>   "query": "Slack Events API retry semantics",
>   "search_depth": "advanced"
> }
> ```
>
> **Representative mutation:** `POST /research`. Expected result: HTTP 200, 201, 204.
>
> **Mutation input**
>
> ```json theme={null}
> {
>   "input": "Compare Slack and Discord webhook retry semantics for an idempotent connector.",
>   "model": "mini"
> }
> ```
>
> **Expected diff:** changes include `researchRequests`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.
>
> **Expected reset:** restores loaded sample.
>
> **Known limits**
>
> * No fresh web access and no guarantee for replay-backed search/crawl/extract/map inputs outside evidence.
>
> **Start this sample**
>
> ```bash theme={null}
> archal sample show tavily.seeded-search-baseline.v1 --raw > archal-tavily-seeded-search-baseline.json
> archal state validate tavily archal-tavily-seeded-search-baseline.json
> archal session create tavily \
>   --state tavily=archal-tavily-seeded-search-baseline.json
> ```
>
> **Inspect the raw state**
>
> ```bash theme={null}
> archal sample show tavily.seeded-search-baseline.v1 --raw
> ```
>
> The packaged JSON artifact is `samples/states/tavily/seeded-search-baseline/state.json` and is 1,031 bytes. The CLI verifies SHA-256 `49cab3b27d28ec154663f27e5d3fb0b28f38ef0f1ef1a54e3dcc99136174826e` before printing it.
>
> Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.

> [accordion] Tavily research team
>
> Exercise three deterministic search topics and two completed research requests for a small research team.
>
> **Sample ID:** `tavily.research-team.v1`
>
> **Category:** `small-team`
>
> **Starting state:** 5 records across `researchRequests`: 2, `searchResults`: 3
>
> **Supported surface:** Stateful deterministic research requests and seeded search-result lookups.
>
> **Required capabilities:** `state.read`, `state.load`, `state.reset`, `rest.research`
>
> **First read:** `POST /search`. Expected result: HTTP 200.
>
> **First-read input**
>
> ```json theme={null}
> {
>   "include_answer": true,
>   "max_results": 5,
>   "query": "Datadog monitor no data behavior",
>   "search_depth": "advanced"
> }
> ```
>
> **Representative mutation:** `POST /research`. Expected result: HTTP 200, 201, 204.
>
> **Mutation input**
>
> ```json theme={null}
> {
>   "input": "Compare Slack and Discord webhook retry semantics for an idempotent connector.",
>   "model": "mini"
> }
> ```
>
> **Expected diff:** changes include `researchRequests`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.
>
> **Expected reset:** restores loaded sample.
>
> **Known limits**
>
> * No fresh web access and no guarantee for replay-backed search/crawl/extract/map inputs outside evidence.
>
> **Start this sample**
>
> ```bash theme={null}
> archal sample show tavily.research-team.v1 --raw > archal-tavily-research-team.json
> archal state validate tavily archal-tavily-research-team.json
> archal session create tavily \
>   --state tavily=archal-tavily-research-team.json
> ```
>
> **Inspect the raw state**
>
> ```bash theme={null}
> archal sample show tavily.research-team.v1 --raw
> ```
>
> The packaged JSON artifact is `samples/states/tavily/research-team/state.json` and is 2,602 bytes. The CLI verifies SHA-256 `88aee1baf49692c8ebb483dd6c6a73a74f9f14cb7f60a9c6e25dd998663a138f` before printing it.
>
> Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.

> [accordion] Tavily populated research corpus
>
> Exercise exact lookup over twenty-five connector topics alongside eight mixed-status research requests.
>
> **Sample ID:** `tavily.research-corpus.v1`
>
> **Category:** `populated`
>
> **Starting state:** 33 records across `researchRequests`: 8, `searchResults`: 25
>
> **Supported surface:** Stateful deterministic research requests and seeded search-result lookups.
>
> **Required capabilities:** `state.read`, `state.load`, `state.reset`, `rest.research`
>
> **First read:** `POST /search`. Expected result: HTTP 200.
>
> **First-read input**
>
> ```json theme={null}
> {
>   "include_answer": true,
>   "max_results": 5,
>   "query": "GitHub protected branch pull request merge",
>   "search_depth": "advanced"
> }
> ```
>
> **Representative mutation:** `POST /research`. Expected result: HTTP 200, 201, 204.
>
> **Mutation input**
>
> ```json theme={null}
> {
>   "input": "Compare Slack and Discord webhook retry semantics for an idempotent connector.",
>   "model": "mini"
> }
> ```
>
> **Expected diff:** changes include `researchRequests`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.
>
> **Expected reset:** restores loaded sample.
>
> **Known limits**
>
> * No fresh web access and no guarantee for replay-backed search/crawl/extract/map inputs outside evidence.
>
> **Start this sample**
>
> ```bash theme={null}
> archal sample show tavily.research-corpus.v1 --raw > archal-tavily-research-corpus.json
> archal state validate tavily archal-tavily-research-corpus.json
> archal session create tavily \
>   --state tavily=archal-tavily-research-corpus.json
> ```
>
> **Inspect the raw state**
>
> ```bash theme={null}
> archal sample show tavily.research-corpus.v1 --raw
> ```
>
> The packaged JSON artifact is `samples/states/tavily/research-corpus/state.json` and is 17,971 bytes. The CLI verifies SHA-256 `a545e645b8c6d3ea4773e102f918b47dde933d237ba4f0c80a9b983045cca2ba` before printing it.
>
> Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.

> [accordion] Tavily failed research request
>
> Verify a valid terminal failed research record with zero response time and no fabricated result.
>
> **Sample ID:** `tavily.failed-research.v1`
>
> **Category:** `edge-case`
>
> **Starting state:** 2 records across `researchRequests`: 1, `searchResults`: 1
>
> **Supported surface:** Stateful deterministic research requests and seeded search-result lookups.
>
> **Required capabilities:** `state.read`, `state.load`, `state.reset`, `rest.research`
>
> **First read:** `GET /research/sample-research-failed`. Expected result: HTTP 200.
>
> **Representative mutation:** `POST /research`. Expected result: HTTP 200, 201, 204.
>
> **Mutation input**
>
> ```json theme={null}
> {
>   "input": "Compare Slack and Discord webhook retry semantics for an idempotent connector.",
>   "model": "mini"
> }
> ```
>
> **Expected diff:** changes include `researchRequests`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.
>
> **Expected reset:** restores loaded sample.
>
> **Known limits**
>
> * No fresh web access and no guarantee for replay-backed search/crawl/extract/map inputs outside evidence.
>
> **Start this sample**
>
> ```bash theme={null}
> archal sample show tavily.failed-research.v1 --raw > archal-tavily-failed-research.json
> archal state validate tavily archal-tavily-failed-research.json
> archal session create tavily \
>   --state tavily=archal-tavily-failed-research.json
> ```
>
> **Inspect the raw state**
>
> ```bash theme={null}
> archal sample show tavily.failed-research.v1 --raw
> ```
>
> The packaged JSON artifact is `samples/states/tavily/failed-research/state.json` and is 1,023 bytes. The CLI verifies SHA-256 `b75c253c2501c167bac7173e10af6dc3642f8042f84364b2ab7b986c6b47f4e0` before printing it.
>
> Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.

> [accordion] Tavily asynchronous research workflow
>
> Read a pending research request, retain a completed exemplar, create one new asynchronous request, and verify reset.
>
> **Sample ID:** `tavily.async-research-workflow.v1`
>
> **Category:** `workflow`
>
> **Starting state:** 3 records across `researchRequests`: 2, `searchResults`: 1
>
> **Supported surface:** Stateful deterministic research requests and seeded search-result lookups.
>
> **Required capabilities:** `state.read`, `state.load`, `state.reset`, `rest.research`
>
> **First read:** `GET /research/sample-research-pending`. Expected result: HTTP 202.
>
> **Representative mutation:** `POST /research`. Expected result: HTTP 200, 201, 204.
>
> **Mutation input**
>
> ```json theme={null}
> {
>   "input": "Compare Slack and Discord webhook retry semantics for an idempotent connector.",
>   "model": "mini"
> }
> ```
>
> **Expected diff:** changes include `researchRequests`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.
>
> **Expected reset:** restores loaded sample.
>
> **Known limits**
>
> * No fresh web access and no guarantee for replay-backed search/crawl/extract/map inputs outside evidence.
>
> **Start this sample**
>
> ```bash theme={null}
> archal sample show tavily.async-research-workflow.v1 --raw > archal-tavily-async-research-workflow.json
> archal state validate tavily archal-tavily-async-research-workflow.json
> archal session create tavily \
>   --state tavily=archal-tavily-async-research-workflow.json
> ```
>
> **Inspect the raw state**
>
> ```bash theme={null}
> archal sample show tavily.async-research-workflow.v1 --raw
> ```
>
> The packaged JSON artifact is `samples/states/tavily/async-research-workflow/state.json` and is 1,425 bytes. The CLI verifies SHA-256 `68cd59acd3e3aa22c51a68230e34a6050754372905e9ab6faffbcd73fef05514` before printing it.
>
> Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.

## Use custom state

Start from a sample when possible. For custom state, inspect the contract with `archal environment describe tavily`, then validate the file before creating a sandbox:

```bash theme={null}
archal state validate tavily state.json
```

Loading state replaces the current collections and establishes a new reset baseline. See [Starting state](https://docs.archal.ai/sandboxes/starting-state.md) before replacing state in an existing sandbox.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.