Use this skill for web search, extraction, mapping, crawling, and research via Tavily’s REST API when web searches are needed and no built-in tool is available, or when Tavily’s LLM-friendly format is beneficial.

Tavily Purpose Provide a curl based interface to Tavily’s REST API for web search, extraction, mapping, crawling, and optional research. Return structured results suitable for LLM workflows and multi step investigations. When to Use Use when a task needs live web information, site extraction, mapping, or crawling. Use when web searches are needed and no built in tool is available, or when Tavily’s LLM friendly output (summaries, chunks, sources, citations) is beneficial. Use when a task requires structured search results, extraction, or site discovery from Tavily. Required Environment Require TAVILY API KEY in the environment. If TAVILY API KEY is missing, prompt the user to provide the API key before proceeding. Base URL and Auth Base URL: https://api.tavily.com Authentication: Authorization: Bearer $TAVILY API KEY Content type: Content Type: application/json Optional project tracking: add X Project ID: <project id if project attribution is needed. Tool Mapping (Tavily REST) 1) search → POST /search Use for web search with optional answer and content extraction. Recommended minimal request: Key parameters (all optional unless noted): query (required): search text search depth : basic advanced fast ultra fast chunks per source : 1–3 (advanced only) max results : 0–20 topic : general news finance time range : day week month year d w m y start date , end date : YYYY MM DD include answer : false true basic advanced include raw content : false true markdown text include images : boolean include image descriptions : boolean include favicon : boolean include domains , exclude domains : string arrays country : country name (general topic only) auto parameters : boolean include usage : boolean Expected response fields: answer (if requested), results[] with title , url , content , score , raw content (optional), favicon (optional) response time , usage , request id 2) extract → POST /extract Use for extracting content from specific URLs. Key parameters: urls (required): array of URLs query : rerank chunks by intent chunks per source : 1–5 (only when query provided) extract depth : basic advanced format : markdown text timeout : 1–60 seconds include usage : boolean Expected response fields: results[] with url , raw content , images , favicon failed results[] , response time , usage , request id 3) map → POST /map Use for generating a site map (URL discovery only). Key parameters: url (required) instructions : natural language guidance (raises cost) max depth : 1–5 max breadth : 1+ limit : 1+ select paths , select domains , exclude paths , exclude domains : arrays of regex strings allow external : boolean timeout : 10–150 seconds include usage : boolean Expected response fields: base url , results[] (list of URLs), response time , usage , request id 4) crawl → POST /crawl Use for site traversal with built in extraction. Key parameters: url (required) instructions : optional; raises cost and enables chunks per source chunks per source : 1–5 (only with instructions ) max depth , max breadth , limit : same as map extract depth : basic advanced format : markdown text include images , include favicon , allow external timeout : 10–150 seconds include usage : boolean Expected response fields: base url , results[] with url , raw content , favicon response time , usage , request id Optional Research Workflow (Deep Investigation) Use when a query needs multi step analysis and citations. create research task → POST /research Expected response fields: request id , created at , status (pending), input , model , response time get research status → GET /research/{request id} Expected response fields: status : completed content : report text or structured object sources[] : { title, url, favicon } streaming research (SSE) Set "stream": true in the POST body and use curl with N to stream events: Handle SSE events (tool calls, tool responses, content chunks, sources, done). Usage Notes Treat search , extract , map , and crawl as the primary endpoints for discovery and content retrieval. Return structured results with URLs, titles, and summaries for easy downstream use. Default to conservative parameters ( search depth: basic , max results: 5 ) unless deeper recall is needed. Reuse consistent request bodies across calls to keep results predictable. Error Handling If any request returns 401/403, prompt for or re check TAVILY API KEY . If timeouts occur, reduce max depth / limit or use search depth: basic . If responses are too large, lower max results or chunks per source .