Tavily (Global, LLM-optimized)

The request body and response structure are passed through transparently to the official Tavily protocol. For full parameter documentation (search_depth, topic, time_range, include_domains, include_answer, include_raw_content, etc.) see the Tavily Search API Reference.

• Endpoint: POST /proxy/tavily/search
• Required parameter: query
• Common parameters: max_results, search_depth (basic / advanced), topic (general / news / finance), time_range, include_answer, include_raw_content, include_domains, exclude_domains

curl $TURING_BASE_URL/proxy/tavily/search \
  -H "Authorization: Bearer $TURING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "latest AI developments 2024",
    "max_results": 5
  }'

Response excerpt:

{
  "query": "latest AI developments 2024",
  "results": [
    {
      "title": "2024 Global Trends in AI - WEKA",
      "url": "https://www.weka.io/resources/analyst-report/2024-global-trends-in-ai/",
      "content": "Discover key AI trends in 2024…",
      "score": 0.7498395
    }
  ],
  "responseTime": 0.86,
  "requestId": "bb84e696-88cd-4b0f-b832-0aba925d312e"
}

Tavily Extract (Web Page Content Extraction)

Extracts clean body text from a set of known URLs. Useful when you already have a list of links (crawled candidates, user-pasted URLs) and need to feed them into embedding / RAG.

• Endpoint: POST /proxy/tavily/extract
• Required parameter: urls (a single URL string or an array of URLs)
• Common parameters: query (focuses extraction on content relevant to this query), extract_depth (basic / advanced; advanced doubles the cost), format (markdown / text), chunks_per_source, include_images, include_favicon, timeout

curl $TURING_BASE_URL/proxy/tavily/extract \
  -H "Authorization: Bearer $TURING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": ["https://example.com/pricing"],
    "extract_depth": "advanced",
    "format": "markdown"
  }'

Response excerpt:

{
  "results": [
    {
      "url": "https://example.com/pricing",
      "raw_content": "# Pricing\n..."
    }
  ],
  "failed_results": []
}

tip

You are only billed for successfully returned URLs; links appearing in failed_results are not charged. Billing formula: (successful URL count / 5) × (1 for basic or 2 for advanced) × $0.008.

Tavily Crawl (Site Crawling)

Starting from a seed URL, follows links outward and extracts the body text of each page encountered. Useful when you don't have an existing URL list and only have an entry page — the crawler automatically discovers and fetches relevant subpages.

• Endpoint: POST /proxy/tavily/crawl
• Required parameter: url (seed URL)
• Common parameters: instructions (natural-language description of which pages to find, e.g. "find pricing pages"), max_depth (link-following depth), max_breadth (maximum links to follow per page), limit (total page crawl limit), select_paths / select_domains (regex allowlists), exclude_paths / exclude_domains (regex blocklists), allow_external (whether to follow off-site links), extract_depth (applies to each crawled page; same semantics as Extract)

curl $TURING_BASE_URL/proxy/tavily/crawl \
  -H "Authorization: Bearer $TURING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "instructions": "find pricing pages",
    "max_depth": 2,
    "limit": 20
  }'

Response excerpt:

{
  "base_url": "https://example.com",
  "results": [
    { "url": "https://example.com/pricing", "raw_content": "..." },
    { "url": "https://example.com/plans", "raw_content": "..." }
  ]
}

tip

Billing = Map cost + Extract cost, both calculated from the same set of successfully crawled pages: map_cost(page count) + extract_cost(page count, extract_depth). For example, 20 successful pages with extract_depth: "basic" gives (20/10 × $0.008) + (20/5 × $0.008) = $0.048.

Tavily Map (Site Structure Discovery)

Discovers a site's URL structure without extracting body content. Useful when you just want to know "what pages exist on this site" and then selectively call Extract on the pages you need.

• Endpoint: POST /proxy/tavily/map
• Required parameter: url (seed URL)
• Common parameters: instructions (natural-language description of which pages to include; setting this doubles the cost), max_depth, max_breadth, limit (same semantics as Crawl), select_paths / select_domains (regex allowlists), exclude_paths / exclude_domains (regex blocklists), allow_external

curl $TURING_BASE_URL/proxy/tavily/map \
  -H "Authorization: Bearer $TURING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "max_depth": 3,
    "select_paths": ["/docs/.*"]
  }'

Response excerpt:

{
  "base_url": "https://example.com",
  "results": [
    "https://example.com/docs/quickstart",
    "https://example.com/docs/api-reference"
  ]
}

tip

Billed by successfully discovered page count. No content extraction makes this the cheapest of the three: (successful page count / 10) × (1 without instructions or 2 with instructions) × $0.008.

Rate Limits and Errors

Extract / Crawl / Map share the same per-key / per-team rate-limiting strategy as /proxy/tavily/search — requests that exceed quota or RPM limits are rejected before consuming any Tavily quota. Errors returned by Tavily are mapped directly to the corresponding HTTP status codes (400/422 for parameter errors, 401 for invalid credentials, 408/504 for timeouts, 429 for rate limiting, 5xx for upstream failures) and are not wrapped uniformly as 500.