# SocialCrawl API: tavily endpoints
# Base URL: https://www.socialcrawl.dev
# Auth: x-api-key header
# Full docs: https://www.socialcrawl.dev/docs/tavily

## GET /v1/tavily/search
Tavily web search with optional LLM-generated answer
Credit cost: 1 (standard)
Parameters:
- query (required): The search query: natural-language free text.
- search_depth (optional, enum: basic | advanced | fast | ultra-fast): Latency-vs-relevance tradeoff. `basic` is the default; `advanced` unlocks `chunks_per_source` and higher-relevance ranking.
- topic (optional, enum: general | news | finance): Search category. Defaults to `general`. Use `news` for time-sensitive queries and `finance` for market data.
- time_range (optional, enum: day | week | month | year | d | w | m | y): Time window relative to now. Accepts `day` / `week` / `month` / `year` (or shorthand `d` / `w` / `m` / `y`).
- max_results (optional, integer): Number of results to return (1-20). Defaults to 5.
- chunks_per_source (optional, integer): Max relevant chunks returned per source (1-5). Only honoured when `search_depth=advanced`. Defaults to 3.
- include_images (optional, boolean): Include images alongside the result content.
- include_image_descriptions (optional, boolean): Include AI-generated descriptions for the returned images.
- include_answer (optional, boolean): Include an LLM-generated answer string synthesised from the top sources.
- include_raw_content (optional, boolean): Include the raw HTML/text alongside the cleaned content.
- include_domains (optional, string): Comma-separated list of domains to restrict results to (e.g. `nytimes.com,reuters.com`).
- exclude_domains (optional, string): Comma-separated list of domains to exclude from results.
- country (optional, string): ISO 3166-1 alpha-2 country code to bias results toward.
- start_date (optional, string): Inclusive lower bound on result publish date (YYYY-MM-DD).
- end_date (optional, string): Inclusive upper bound on result publish date (YYYY-MM-DD).
curl -G "https://www.socialcrawl.dev/v1/tavily/search" \
  --data-urlencode "query=claude opus 4.7 release notes" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/tavily/extract
Extract clean content from one or more URLs
Credit cost: 1 (standard)
Parameters:
- urls (required): Comma-separated list of URLs to extract (max 20).
- extract_depth (optional, enum: basic | advanced): Extraction strategy. `basic` is the default and faster; `advanced` handles harder pages but takes longer.
- format (optional, enum: markdown | text): Output format for the extracted content. `markdown` (default) preserves structure; `text` is plain.
- include_images (optional, boolean): Include images extracted from each URL.
- include_favicon (optional, boolean): Include the favicon URL for each page.
- timeout (optional, integer): Per-URL timeout in seconds (1-60).
curl -G "https://www.socialcrawl.dev/v1/tavily/extract" \
  --data-urlencode "urls=https://en.wikipedia.org/wiki/Lionel_Messi" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/tavily/map
Map a website's sitegraph
Credit cost: 1 (standard)
Parameters:
- url (required): Root URL to begin mapping.
- max_depth (optional, integer): Maximum link depth from the root URL. Defaults to 1.
- max_breadth (optional, integer): Maximum number of links followed per level (per page). Defaults to 20.
- limit (optional, integer): Total number of links the mapper will process before stopping. Defaults to 50.
- instructions (optional, string): Natural-language instructions for the mapper (e.g. 'Find all pages related to API documentation').
- select_paths (optional, string): Comma-separated regex patterns: only include URLs whose path matches.
- select_domains (optional, string): Comma-separated regex patterns: only include URLs whose domain matches.
- exclude_paths (optional, string): Comma-separated regex patterns: exclude URLs whose path matches.
- exclude_domains (optional, string): Comma-separated regex patterns: exclude URLs whose domain matches.
- allow_external (optional, boolean): Whether to follow / return links to external domains. Defaults to true.
- timeout (optional, integer): Maximum time in seconds (10-150).
- categories (optional, string): Comma-separated list of category hints to bias mapping toward.
curl -G "https://www.socialcrawl.dev/v1/tavily/map" \
  --data-urlencode "url=https://docs.tavily.com" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/tavily/crawl
Crawl a website with LLM-driven path selection
Credit cost: 1 (standard)
Parameters:
- url (required): Root URL to begin crawling.
- max_depth (optional, integer): Maximum link depth from the root URL. Defaults to 1.
- max_breadth (optional, integer): Maximum number of links followed per level (per page). Defaults to 20.
- limit (optional, integer): Total number of pages the crawler will process before stopping. Defaults to 50.
- instructions (optional, string): Natural-language instructions for the crawler (e.g. 'Find all product pages with pricing').
- select_paths (optional, string): Comma-separated regex patterns: only crawl URLs whose path matches.
- select_domains (optional, string): Comma-separated regex patterns: only crawl URLs whose domain matches.
- exclude_paths (optional, string): Comma-separated regex patterns: skip URLs whose path matches.
- exclude_domains (optional, string): Comma-separated regex patterns: skip URLs whose domain matches.
- allow_external (optional, boolean): Whether to follow links to external domains. Defaults to true.
- extract_depth (optional, enum: basic | advanced): Per-page extraction strategy. `basic` is faster; `advanced` handles harder pages.
- format (optional, enum: markdown | text): Output format for extracted content. `markdown` (default) or `text`.
- categories (optional, string): Comma-separated list of category hints to bias the crawl toward.
curl -G "https://www.socialcrawl.dev/v1/tavily/crawl" \
  --data-urlencode "url=https://docs.tavily.com" \
  -H "x-api-key: YOUR_API_KEY"