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

# Tavily

> Tavily enriches LLM prompts with fresh web search context before inference.

[Tavily](https://www.tavily.com/) provides a search API purpose-built for AI agents. Portkey's Tavily guardrail injects relevant web search results into the request before it reaches the LLM, so the model can answer with current online information.

<Card title="Get Started with Tavily" href="https://www.tavily.com/" />

<Note>
  Requires Backend `v1.16.0+`.
</Note>

## Using Tavily with Portkey

### 1. Add Tavily Credentials to Portkey

* Click on the `Admin Settings` button on Sidebar
* Navigate to `Plugins` tab under Organisation Settings
* Click on the edit button for the **Tavily** integration
* Add your **Tavily API Key** (obtain this from your Tavily account)

### 2. Add Tavily's Guardrail Check

* Navigate to the `Guardrails` page and click the `Create` button
* Search for **"Tavily Online Search"** and click `Add`
* Configure the search behaviour (all parameters are optional):

| Parameter                  | Type                             | Description                                                                                 | Default                   |
| -------------------------- | -------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------- |
| `prefix`                   | string                           | Text inserted before the Tavily search context in the prompt                                | `\n<web_search_context>`  |
| `suffix`                   | string                           | Text inserted after the Tavily search context in the prompt                                 | `\n</web_search_context>` |
| `maxResults`               | number                           | Maximum number of Tavily search results to return                                           | `5`                       |
| `searchDepth`              | enum                             | Latency vs. relevance tradeoff: `advanced`, `basic`, `fast`, `ultra-fast`                   | —                         |
| `chunksPerSource`          | number                           | Maximum number of chunks returned per source (advanced/fast depths)                         | `3`                       |
| `topic`                    | enum                             | Category of results: `general`, `news`, `finance`                                           | —                         |
| `timeRange`                | enum                             | Filter by recency: `day` / `week` / `month` / `year` (or `d` / `w` / `m` / `y`)             | —                         |
| `startDate`                | string                           | Return results after this date (`YYYY-MM-DD`)                                               | —                         |
| `endDate`                  | string                           | Return results before this date (`YYYY-MM-DD`)                                              | —                         |
| `includeAnswer`            | boolean \| `basic` \| `advanced` | Include a Tavily-generated answer in the response                                           | `false`                   |
| `includeRawContent`        | boolean \| `markdown` \| `text`  | Include cleaned, parsed HTML content for each result                                        | `false`                   |
| `includeImages`            | boolean                          | Include query-related images and per-result images                                          | `false`                   |
| `includeImageDescriptions` | boolean                          | Include descriptive text for each image                                                     | `false`                   |
| `includeFavicon`           | boolean                          | Include the favicon URL for each result                                                     | `false`                   |
| `includeDomains`           | string\[]                        | Restrict results to the listed domains                                                      | —                         |
| `excludeDomains`           | string\[]                        | Exclude results from the listed domains                                                     | —                         |
| `country`                  | string                           | Boost results from a specific country (only when `topic = general`)                         | —                         |
| `autoParameters`           | boolean                          | Let Tavily automatically configure search parameters from the query                         | `false`                   |
| `exactMatch`               | boolean                          | Return only results matching exact quoted phrases                                           | `false`                   |
| `includeUsage`             | boolean                          | Include Tavily credit usage information in the response metadata                            | `false`                   |
| `safeSearch`               | boolean                          | Enterprise-only. Filters adult or unsafe content. Not supported for fast/ultra-fast depths. | `false`                   |
| `timeout`                  | number                           | Maximum time to wait for the Tavily request (ms)                                            | `30000`                   |

* Set any `actions` you want on your check, and create the Guardrail!

<Note>
  Guardrail Actions allow you to orchestrate your guardrails logic. You can learn more about them [here](/product/guardrails#there-are-6-types-of-guardrail-actions)
</Note>

| Check Name           | Description                                                                                            | Supported Hooks     |
| -------------------- | ------------------------------------------------------------------------------------------------------ | ------------------- |
| Tavily Online Search | Adds relevant Tavily web results to the prompt so the model can answer with current online information | `beforeRequestHook` |

### 3. Add Guardrail ID to a Config and Make Your Request

* When you save a Guardrail, you'll get an associated Guardrail ID — add this ID to the `input_guardrails` param in your Portkey Config
* Create these Configs in Portkey UI, save them, and get an associated Config ID to attach to your requests. [More here](/product/ai-gateway/configs).

```json theme={"system"}
{
  "input_guardrails": ["guardrails-id-xxx"]
}
```

<Tabs>
  <Tab title="NodeJS">
    ```js theme={"system"}
    const portkey = new Portkey({
        apiKey: "PORTKEY_API_KEY",
        config: "pc-***"
    });
    ```
  </Tab>

  <Tab title="Python">
    ```py theme={"system"}
    portkey = Portkey(
        api_key="PORTKEY_API_KEY",
        config="pc-***"
    )
    ```
  </Tab>

  <Tab title="cURL">
    ```sh theme={"system"}
    curl https://api.portkey.ai/v1/chat/completions \
      -H "Content-Type: application/json" \
      -H "x-portkey-api-key: $PORTKEY_API_KEY" \
      -H "x-portkey-config: $CONFIG_ID" \
      -d '{
        "model": "gpt-4o-mini",
        "messages": [{"role": "user", "content": "What are the latest changes to the EU AI Act?"}]
      }'
    ```
  </Tab>
</Tabs>

For more, refer to the [Config documentation](/product/ai-gateway/configs).

## Get Support

If you face any issues with the Tavily integration, join the [Portkey community forum](https://discord.gg/portkey-llms-in-prod-1143393887742861333) for assistance.