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

# Tavily — web search

> The public search engine behind Scout — grounded searches with URL citations.

You ask the researcher on your team, "what did our competitor just announce?" A minute later you have an answer — with the source links behind every line, not a confident guess pulled from stale training data. That researcher is [Scout](/en/agents/scout), reaching out to the live web on the org's behalf, and Tavily is the engine it searches with.

What that leaves off your plate: nobody has to open ten tabs, skim, and paste links back into a doc. The search, the reading, and the citing happen for you.

## What it is

[Tavily](https://tavily.com) is a search engine **built for AI agents**. Unlike a generic search API, Tavily returns pre-structured snippets designed for grounding: each result comes with a source URL, relevance score, and context snippet.

[Scout](/en/agents/scout) uses Tavily as its primary engine for all public searches.

## Why Tavily (and not something "simpler")

| Alternative                  | Why it's NOT the default                                              |
| ---------------------------- | --------------------------------------------------------------------- |
| Direct Google search         | No stable public API + restrictive terms of service                   |
| Generic web scraping         | Fragile, costly, high risk of being blocked                           |
| Bing Search API              | Works, but Tavily delivers better-curated results for LLM consumption |
| Built-in web search (native) | Used as a **fallback** when Tavily is unavailable                     |

## Connection (BYO key)

The integration is **Bring Your Own Key**:

<Steps>
  <Step title="Create a Tavily account">
    [tavily.com](https://tavily.com) → the free tier covers initial testing.
    Paid plans are available for higher volume.
  </Step>

  <Step title="Get your API key">
    In the Tavily dashboard, copy your API key.
  </Step>

  <Step title="Paste it into Apollo Space">
    **Settings → Integrations → Tavily** → paste the key.
  </Step>

  <Step title="Done">
    Scout will start using that key automatically. You can swap
    or revoke it at any time.
  </Step>
</Steps>

<Info>
  The key is stored **encrypted** and isolated per organization — another
  Apollo Space customer cannot see your key. See [Security](/en/trust/security).
</Info>

## Search tier

Tavily exposes two search tiers:

| Tier         | What it delivers                                       | When it makes sense                  |
| ------------ | ------------------------------------------------------ | ------------------------------------ |
| **Basic**    | Fast response, short snippets                          | Exploratory research, simple queries |
| **Advanced** | Deeper content + larger chunks + additional processing | Critical analysis, fact-checking     |

Scout uses the **basic** tier by default — the best cost/quality ratio for the typical use case. Teams with specific needs can configure advanced via support.

## Automatic fallback

If a Tavily search fails (key not configured, Tavily rate limit, network error), Scout **automatically falls back** to the platform's built-in `web_search` — you won't see an interruption, just a note in the trace indicating the fallback was used.

## Per-org cap

To protect your Tavily key from accidental exhaustion (search loops during debugging, misconfigured agent), Apollo Space applies an **internal searches-per-second cap per organization**.

When the cap fires:

1. The current search falls back to the built-in provider for a short period
2. The cap-fire is recorded in the org's event history
3. After the cooldown, Tavily resumes being used normally

This is **independent** of Tavily's own rate limits — it is an extra protection layer that Apollo Space applies on top of your key.

## Dry-run mode for development

In test/dev environments, Apollo Space operates in **dry-run** mode by default:
Scout returns 3 canned snippets (with URLs clearly marked as `example.com`) without actually calling Tavily.

This protects your key from being consumed in non-production environments.
In production, dry-run is off by default.

## Costs

| Where it falls                                          | Who pays                                |
| ------------------------------------------------------- | --------------------------------------- |
| **Tavily search** (per API call)                        | Your Tavily account directly            |
| **Scout orchestration** (LLM + Apollo Space processing) | Your [Stars](/en/billing/stars) balance |

The Tavily invoice goes directly to you — Apollo Space does not intermediate payment.

## Next steps

<CardGroup cols={2}>
  <Card title="Scout — who uses Tavily" icon="binoculars" href="/en/agents/scout">
    The persona that triggers the searches.
  </Card>

  <Card title="Stars" icon="star" href="/en/billing/stars">
    How Scout usage (orchestration) factors into billing.
  </Card>

  <Card title="Apify (enrichment)" icon="map-pin" href="/en/integrations/apify">
    For Google Maps search + site enrichment, Apollo Space uses
    Apify, not Tavily.
  </Card>
</CardGroup>