Skip to main content

Tavily Search Provider (Legacy)

Overview​

The Tavily provider (src/mastra/providers/tavily-search.ts) wraps the Tavily API to offer fast, domain-aware web search results. This provider is currently used for admin diagnostic tools and workflows requiring explicit domain filtering or result ranking control.

note

Primary Search Solution: The platform now uses Perplexity Search as the primary search solution for the Reasoning Engine and most workflows. Tavily remains available for diagnostic tools and specific use cases requiring domain filtering.

API Surface​

  • quickSearch(query, options) – Primary entry point for most workloads; supports domain filters, topics, result limits, and optional AI summaries.
  • domainSearch(query, domains) – Convenience wrapper for restricting results to a known set of domains.
  • newsSearch(query, days) / financeSearch(query) – Topic-focused helpers that configure Tavily’s topic filters.

Each helper returns structured results detailing the answer summary (if requested), per-result metadata, relevance scores, and optional image observations.

Configuration​

Required environment variables:

  • TAVILY_API_KEY – Your Tavily API key (obtainable from https://tavily.com).
  • TAVILY_TIMEOUT_MS – Maximum allowed time per request (default 30 seconds).

Optional tuning knobs:

  • TAVILY_DEFAULT_SEARCH_DEPTH (basic | advanced) – Controls whether cached or fresh results are preferred.
  • TAVILY_DEFAULT_MAX_RESULTS – Default number of results returned (typically 5).
  • TAVILY_DEBUG_TIMINGS – Enable timing logs for debugging provider latency.

The provider automatically retries on transient failures and surfaces structured errors (including rate limit hints) for callers that want to fallback.

Use Cases​

  • Admin Diagnostics: admin-test-tavily-search exercises the provider for testing and debugging web search integration.
  • Base Tavily Search Tool: Platform-level tool (src/mastra/tools/base/tavily-search.tool.ts) available for workflows needing domain filtering.
  • Domain-Filtered Searches: Use when explicit control over included/excluded domains is required.
  • Direct Provider Calls: Workflows can call quickSearch, domainSearch, or topic-specific helpers directly for custom search logic.
note

For general web search needs, consider using Perplexity Search which provides AI-powered synthesis and automatic citation tracking in a single API call.

Example Response Structure​

{
  "answer": "Summarized data about the query",
  "results": [
    {
      "title": "Article Title",
      "url": "https://example.com/article",
      "content": "Snippet...",
      "score": 0.85,
      "publishedDate": "2026-01-05"
    }
  ],
  "responseTime": 234,
  "configured": true,
  "resultCount": 1,
  "parameters": {
    "query": "...",
    "topic": "general",
    "maxResults": 5
  }
}

Provider Integration Tips​

  1. Always ensure TAVILY_API_KEY is populated before calling any helper; the provider short-circuits and returns configured: false when the key is missing.
  2. Use includeDomains / excludeDomains when you need to avoid specific publishers (e.g., autop-run tests or restricted content sources).
  3. Pair provider calls with caching or deduplication logic when multiple workflows use the same query during a single run.
  4. The provider normalizes the Tavily payload so downstream code only needs to iterate results and trust score ordering.