> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.runtype.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.runtype.com/_mcp/server.

# Exa (web search)

Use Exa to search the web from an Agent or a Flow. Exa is available as the built-in **Exa** tool for Agents and as the **Exa Search API** provider for the **AI Search** Flow step. Exa uses neural and keyword search and returns results with optional summaries, highlights, and full page text.

## Set up Exa

You can use Exa without an Exa account. Without your own key, Exa calls use a Runtype platform key, and Runtype tracks their cost as platform-key spend. For how platform keys are billed and limited, see [Platform keys vs. BYOK](/user-guide/getting-started/platform-keys-vs-byok).

To use your own Exa account, follow these steps:

1. Create an account at [Exa](https://exa.ai).
2. Get an Exa API key.
3. In Runtype, go to **Settings > Integrations**.
4. Find **Exa**.
5. In **Exa API Key**, enter your key.
6. Click **Save Key**.

To go back to the platform key, click **Remove Key** in the **Exa** section.

## Add Exa to an Agent

To add Exa to an Agent, follow these steps:

1. Open your Agent.
2. In the tools strip, click **Add tool**. The tool picker opens.
3. In the **Web search** category, select **Exa**.
4. Close the picker and save the Agent.

To attach Exa in an Agent definition, add `builtin:exa` to `tools.toolIds`:

**`Agent tools configuration`**

```json title="Agent tools configuration"
{
  "tools": {
    "toolIds": ["builtin:exa"]
  }
}
```

You can list `builtin:exa` in the same `tools` configuration as runtime tools that you define for a single request. For details, see [Runtime tools](/user-guide/tools/runtime-tools).

### Tool parameters

When an Agent calls Exa, the model supplies these parameters. If the model leaves out an optional parameter, the tool uses the listed default.

| Parameter            | Description                                                                       | Requirement or default         |
| -------------------- | --------------------------------------------------------------------------------- | ------------------------------ |
| `query`              | Search query.                                                                     | Required.                      |
| `searchType`         | Select `auto`, `neural` for semantic search, or `keyword` for traditional search. | Optional. Defaults to `auto`.  |
| `numResults`         | Set the number of results from 1 to 10.                                           | Optional. Defaults to `5`.     |
| `summary`            | Include an AI-generated summary for each result.                                  | Optional. Defaults to `true`.  |
| `highlights`         | Include relevant highlights from each result.                                     | Optional. Defaults to `true`.  |
| `text`               | Include the full page text for each result.                                       | Optional. Defaults to `false`. |
| `includeDomains`     | Restrict results to specific domains.                                             | Optional.                      |
| `excludeDomains`     | Exclude specific domains from results.                                            | Optional.                      |
| `startPublishedDate` | Filter results published after an ISO 8601 date.                                  | Optional.                      |
| `endPublishedDate`   | Filter results published before an ISO 8601 date.                                 | Optional.                      |

### Tool results

The tool returns the search query, the Exa results, and a result count. Each item in `results` includes fields such as `title`, `url`, `publishedDate`, `author`, and, when requested, `summary`, `highlights`, and `text`:

**`Exa tool result`**

```json title="Exa tool result"
{
  "success": true,
  "query": "open-source vector databases",
  "results": [
    {
      "title": "Example article",
      "url": "https://example.com/article",
      "publishedDate": "2026-05-01T00:00:00.000Z",
      "summary": "A comparison of open-source vector databases.",
      "highlights": ["..."]
    }
  ],
  "resultCount": 1
}
```

## Use Exa in a Flow

To search with Exa in a Flow, follow these steps:

1. Add an **AI Search** step.
2. In **Search for**, enter the query. You can use variables, for example `{{topic}}`.
3. In the provider list, select **Exa Search API**.
4. In **returning**, set the number of results.

The **Exa Search API** option appears only when Exa is available to your account.

The step's **Exa Options** settings control what Exa returns:

* **search type**: **Auto (Recommended)**, **Neural Search**, or **Keyword Search**.
* **Content Options**: turn on **Include full page text**, **Include AI summary**, or **Include highlights**. All three are off by default.
* **category filter**: limit results to one Exa category, such as `research paper`.

The **Only search these domains** and **Exclude these domains** filters also apply to Exa. The **Date Range** fields don't apply to Exa. To filter an Exa search by date, set `exaStartPublishedDate` and `exaEndPublishedDate` in the step definition.

### Step configuration

In a Flow definition, an AI Search step that uses Exa has `type: "search"` and `provider: "exa"`:

**`AI Search step with Exa`**

```json title="AI Search step with Exa"
{
  "type": "search",
  "name": "Research topic",
  "config": {
    "provider": "exa",
    "query": "{{topic}}",
    "outputVariable": "searchOutput",
    "exaSearchType": "auto",
    "exaNumResults": 10,
    "exaContents": { "summary": true, "highlights": true }
  }
}
```

The step accepts these Exa fields:

| Field                                          | Description                                                                                      |
| ---------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| `exaSearchType`                                | `auto`, `neural`, or `keyword`. Defaults to `auto`.                                              |
| `exaNumResults`                                | Number of results from 1 to 100. When unset, the step uses `maxResults`, then `5`.               |
| `exaContents`                                  | Object with the booleans `text`, `summary`, and `highlights`.                                    |
| `exaCategory`                                  | Exa category to search in.                                                                       |
| `exaIncludeDomains`, `exaExcludeDomains`       | Domain lists. When unset, the step uses `allowedDomains` and `blockedDomains`.                   |
| `exaStartPublishedDate`, `exaEndPublishedDate` | Publication date range, as an ISO 8601 date (`2026-01-01`) or datetime (`2026-01-01T00:00:00Z`). |
| `exaStartCrawlDate`, `exaEndCrawlDate`         | Range for when Exa crawled the page, in the same format.                                         |

### Step output

The step writes an object with `query`, `results`, `citations`, and `metadata` to its output variable. Each result includes `title`, `url`, `content`, `publishedDate`, `author`, and `score`, plus `summary`, `highlights`, and `text` when you request them. Each citation includes `id`, `url`, `title`, `source` (the site's hostname), `publishedDate`, and `author`.

To use the results in a later Prompt step, reference the output variable:

**`Prompt step`**

```text title="Prompt step"
Summarize these search results and cite each source:

{{searchOutput.results}}

Sources: {{searchOutput.citations}}
```

By default, a failed AI Search step doesn't stop the Flow. It writes `{ "error": "...", "results": [] }`, or the step's default value, to the output variable. To stop the Flow instead, change the step's error handling. For details, see [Flow step types overview](/user-guide/flows/flow-step-types-overview#when-a-step-fails).

## Troubleshooting

The following table lists common Exa errors. The Agent tool and the Flow step word the missing-key error differently, and the Agent tool adds the prefix `Exa search failed:` to most errors.

| Error                                                                   | Cause                                                                       | Fix                                                                                              |
| ----------------------------------------------------------------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| `Exa API key not configured` or `Exa API key required but not provided` | No Exa key is available for your account.                                   | Add your Exa API key in **Settings > Integrations**.                                             |
| `Platform key spend credit is exhausted`                                | Your platform-key credit balance is used up. The Agent tool reports this.   | Set a default payment method in **Billing**, or add your own Exa key.                            |
| `Exa API error (STATUS): ...`                                           | Exa rejected the request. For example, your key is invalid or out of quota. | Check your key and usage in the Exa dashboard. To use the platform key instead, remove your key. |

## Use cases

Use Exa for the following tasks:

* Research current information across web sources.
* Verify claims against web sources.
* Find reference material for content creation.
* Find companies or contacts for lead generation.
* Research sites that block automated requests. Exa retrieves content through its own infrastructure, so it can work when **Fetch URL** requests are blocked.

## Next steps

Continue with these pages:

* [Built-in tools](/user-guide/tools/built-in-tools): add Exa and other tools to Agents and Flows.
* [Agent and flow templates](/user-guide/flows/agent-and-flow-templates): start from a template that uses Exa.
* [Flow step types overview](/user-guide/flows/flow-step-types-overview): learn about the **AI Search** step and other steps.
* [Firecrawl (web scraping)](/user-guide/integrations/firecrawl-web-scraping): extract content from pages that Exa finds.
* [What are Agents?](/user-guide/agents/what-are-agents): build an Agent that uses Exa.
* [Using crawl, search, and paginate-api steps](/user-guide/flows/using-crawl-search-and-paginate-steps): crawl a website, run an AI search, and page through an API.