Tavily

The tavily connector holds the API key and talks to Tavily, a search API built for LLMs: it returns ranked results with content already cleaned and chunked, so a flow can hand them straight to a model. Pair tavily-search with ai-agent to search the live web and then reason over what came back.

tavily connector

It is a service connector and provides no source. The blocks that bind to it are tavily-search, tavily-extract, tavily-crawl and tavily-map.

Settings

An apiBaseURL setting also overrides the API base (default https://api.tavily.com), mainly for tests; it is not exposed in the editor.

samples/web-research uses every block on this page.

env:
  - name: TAVILY_API_KEY
    required: true

connectors:
  - name: search
    type: tavily
    settings:
      apiKey: ${TAVILY_API_KEY}

Error handling

Tavily signals errors with an HTTP status ≥ 400 carrying {detail: {error}}. Every block has a failOnError setting (default true): when true a Tavily error fails the flow, when false the message passes through unchanged.

Where the result goes

Every block follows the same convention as pinecone: the response becomes the body. Set resultVar to keep the incoming body and store the response in a variable instead.

tavily-search block

Tavily Search searches the live web and returns the ranked results, optionally with a synthesized answer.

- type: tavily-search
  name: research
  settings:
    connector: search
    query: body.question
    searchDepth: advanced
    topic: general
    maxResults: 8
    includeAnswer: advanced
    excludeDomains: '["pinterest.com"]'
    resultVar: hits

country and language do not use the same convention: country takes Tavily's own lowercase country names from a fixed list, while language takes an ISO 639-1 code. Both are passed through verbatim, so an unsupported value is rejected by Tavily rather than by the block.

An enum left unset is omitted from the request, so Tavily's own default applies. none on includeAnswer and includeRawContent means the same thing.

The response carries query, results (each with title, url, content, score, and raw_content when requested), answer when includeAnswer was set, plus response_time and usage.

A domain-list setting takes a CEL expression, so it can be a literal list, or come from the message:

    includeDomains: body.allowedSites

Both accept a bare string as a one-element list, matching Tavily's own tolerance.

tavily-extract block

Tavily Extract pulls clean, LLM-ready content out of URLs you already have, which is how a flow follows a link it was handed.

The response carries results (each with url, raw_content, and images/favicon when requested) and failed_results, the URLs that could not be processed.

- type: tavily-extract
  name: read-sources
  settings:
    connector: search
    urls: body.results.map(r, r.url)
    format: markdown
    failOnPartial: true

tavily-crawl block

Tavily Crawl walks a site from a root URL and returns each page's extracted content, optionally steered by a natural-language instruction.

The response carries base_url and results, each with url and raw_content.

- type: tavily-crawl
  name: crawl-docs
  settings:
    connector: search
    url: '"https://docs.example.com"'
    instructions: '"collect every page describing the API"'
    maxDepth: 3
    limit: 200
    allowExternal: false

tavily-map block

Tavily Map discovers a site's link graph from a root URL and returns the URLs found, without extracting any content. It is crawl's cheap sibling: use it to decide what is worth crawling or extracting.

It takes the same traversal settings as tavily-crawl (url, instructions, maxDepth, maxBreadth, limit, selectPaths, excludePaths, selectDomains, excludeDomains, allowExternal) plus resultVar and failOnError. It has no extractDepth or format, because it extracts nothing.

The response carries base_url and results, a flat list of discovered URLs.

- type: tavily-map
  name: survey
  settings:
    connector: search
    url: body.site
    maxDepth: 2
    resultVar: siteUrls