> ## 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         | Preview                                       |
| Curated samples | 5                                             |

Preview means the environment is included for testing, but its upstream coverage is incomplete. Verify the operations your test depends on.

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

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

<AccordionGroup>
  <Accordion title="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>

  <Accordion title="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>

  <Accordion title="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>

  <Accordion title="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>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## 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](/sandboxes/starting-state) before replacing state in an existing sandbox.