tavily
Module tavily
API
Definitions
ayesha/tavily
Overview
Tavily is a search engine built for AI agents and LLMs. Its REST API provides web search, content extraction, site crawling, site mapping, and agentic deep research, all tuned to return results that are easy for an LLM to consume.
The Ballerina Tavily connector lets you call all of these operations from a Ballerina application: search the web, extract clean content from a set of URLs, crawl or map a site graph, kick off and poll a deep research task, and track API key/account credit usage.
This is an unofficial connector for the Tavily API. It is not reviewed, approved, or endorsed by Tavily.
Key features
- Search the web with adjustable depth, topic, freshness, and domain filters, and optionally get back an LLM-generated answer
- Extract cleaned, LLM-ready content from a single URL or a batch of up to 20 URLs
- Crawl a site graph following configurable depth/breadth rules, extracting content as it goes
- Map a website to discover its URL structure without extracting page content
- Kick off a deep, agentic research task and poll it until it completes, with cited sources
- Track credit usage per API key and for the account as a whole
Setup guide
The Tavily API requires an API key for every request.
- Sign up for a free account at the Tavily platform.
- Generate an API key from the dashboard. It will look like
tvly-YOUR_API_KEY.
Quickstart
To use the tavily connector in your Ballerina application, follow these steps:
Step 1: Import the connector
Import the ayesha/tavily package into your Ballerina project.
import ayesha/tavily;
Step 2: Instantiate a new connector
Create a tavily:Client using your API key as a bearer token.
tavily:Client tavilyClient = check new ({ auth: { token: "<Your Tavily API Key>" } });
Step 3: Invoke the connector operation
Now, utilize the available connector operations.
Search the web
tavily:SearchResponse response = check tavilyClient->/search.post({ query: "Who is Leo Messi?", include_answer: true }); io:println(response.answer);
Extract content from a URL
tavily:ExtractResponse response = check tavilyClient->/extract.post({ urls: ["https://ballerina.io"] }); io:println(response.results[0].raw_content);
Clients
tavily: Client
Tavily is a search engine built for AI agents and LLMs. This OpenAPI specification covers the Tavily REST API, including web search, content extraction, site crawling, site mapping, deep research, and usage tracking.
Authentication
All endpoints require a Tavily API key supplied as a bearer token:
Authorization: Bearer tvly-YOUR_API_KEY
Get a free API key from the Tavily platform.
Optional tracking headers
Most endpoints accept optional headers to organize and analyze requests:
X-Project-ID, X-Session-Id, and X-Human-Id.
Constructor
Gets invoked to initialize the connector.
init (ConnectionConfig config, string serviceUrl)- config ConnectionConfig - The configurations to be used when initializing the
connector
- serviceUrl string "https://api.tavily.com" - URL of the target service
post search
function post search(SearchRequest payload, SearchHeaders headers) returns SearchResponse|errorSearch the web
Parameters
- payload SearchRequest -
- headers SearchHeaders (default {}) - Headers to be sent with the request
Return Type
- SearchResponse|error - Successful search
post extract
function post extract(ExtractRequest payload, ExtractHeaders headers) returns ExtractResponse|errorExtract content from URLs
Parameters
- payload ExtractRequest -
- headers ExtractHeaders (default {}) - Headers to be sent with the request
Return Type
- ExtractResponse|error - Extraction results
post crawl
function post crawl(CrawlRequest payload, CrawlHeaders headers) returns CrawlResponse|errorCrawl a website
Parameters
- payload CrawlRequest -
- headers CrawlHeaders (default {}) - Headers to be sent with the request
Return Type
- CrawlResponse|error - Crawl results
post 'map
function post 'map(MapRequest payload, MapHeaders headers) returns MapResponse|errorMap a website
Parameters
- payload MapRequest -
- headers MapHeaders (default {}) - Headers to be sent with the request
Return Type
- MapResponse|error - Map results
post research
function post research(ResearchRequest payload, CreateResearchHeaders headers) returns ResearchTaskCreated|errorCreate a research task
Parameters
- payload ResearchRequest -
- headers CreateResearchHeaders (default {}) - Headers to be sent with the request
Return Type
- ResearchTaskCreated|error - Research task created
get research/[string request_id]
function get research/[string request_id](map<string|string[]> headers) returns ResearchTaskCompleted|ResearchTaskFailed|ResearchTaskPending|errorGet research task status and results
Return Type
- ResearchTaskCompleted|ResearchTaskFailed|ResearchTaskPending|error - Task completed or failed
get usage
function get usage(GetUsageHeaders headers) returns UsageResponse|errorGet usage information
Parameters
- headers GetUsageHeaders (default {}) - Headers to be sent with the request
Return Type
- UsageResponse|error - Usage information
Records
tavily: AccountUsage
Fields
- current_plan? string - The account's current plan.
- plan_usage? int - Credits used against the plan allowance.
- plan_limit? int - The plan credit limit.
- paygo_usage? int - Credits used under pay-as-you-go.
- paygo_limit? int - The pay-as-you-go credit limit.
- search_usage? int - Account-wide credits used by search requests.
- extract_usage? int - Account-wide credits used by extract requests.
- crawl_usage? int - Account-wide credits used by crawl requests.
- map_usage? int - Account-wide credits used by map requests.
- research_usage? int - Account-wide credits used by research requests.
tavily: ConnectionConfig
Provides a set of configurations for controlling the behaviours when communicating with a remote HTTP endpoint.
Fields
- auth BearerTokenConfig - Configurations related to client authentication
- httpVersion HttpVersion(default http:HTTP_2_0) - The HTTP version understood by the client
- http1Settings ClientHttp1Settings(default {}) - Configurations related to HTTP/1.x protocol
- http2Settings ClientHttp2Settings(default {}) - Configurations related to HTTP/2 protocol
- timeout decimal(default 30) - The maximum time to wait (in seconds) for a response before closing the connection
- forwarded string(default "disable") - The choice of setting
forwarded/x-forwardedheader
- followRedirects? FollowRedirects - Configurations associated with Redirection
- poolConfig? PoolConfiguration - Configurations associated with request pooling
- cache CacheConfig(default {}) - HTTP caching related configurations
- compression Compression(default http:COMPRESSION_AUTO) - Specifies the way of handling compression (
accept-encoding) header
- circuitBreaker? CircuitBreakerConfig - Configurations associated with the behaviour of the Circuit Breaker
- retryConfig? RetryConfig - Configurations associated with retrying
- cookieConfig? CookieConfig - Configurations associated with cookies
- responseLimits ResponseLimitConfigs(default {}) - Configurations associated with inbound response size limits
- secureSocket? ClientSecureSocket - SSL/TLS-related options
- proxy? ProxyConfig - Proxy server related options
- socketConfig ClientSocketConfig(default {}) - Provides settings related to client socket configuration
- validation boolean(default true) - Enables the inbound payload validation functionality which provided by the constraint package. Enabled by default
- laxDataBinding boolean(default true) - Enables relaxed data binding on the client side. When enabled,
nilvalues are treated as optional, and absent fields are handled asnilabletypes. Enabled by default.
tavily: CrawlHeaders
Represents the Headers record for the operation: crawl
Fields
- X\-Session\-Id? string - Optional session identifier for grouping related requests in analytics.
- X\-Human\-Id? string - Optional identifier for the end user driving the request.
- X\-Project\-ID? string - Optional project ID to scope the request to a specific project.
tavily: CrawlRequest
Fields
- url string - The root URL to begin the crawl.
- instructions? string? - Natural language instructions for the crawler. Increases cost to 2 credits per 10 successful pages.
- chunks_per_source int(default 3) - Maximum relevant chunks returned per source. Only available with
instructions.
- max_depth int(default 1) - Max depth of the crawl — how far from the base URL the crawler can explore.
- max_breadth int(default 20) - Max number of links to follow per level of the tree.
- 'limit int(default 50) - Total number of links the crawler will process before stopping.
- select_paths? string[]? - Regex patterns to select only URLs with specific path patterns.
- select_domains? string[]? - Regex patterns to restrict crawling to specific domains or subdomains.
- exclude_paths? string[]? - Regex patterns to exclude URLs with specific path patterns.
- exclude_domains? string[]? - Regex patterns to exclude specific domains from crawling.
- allow_external boolean(default true) - Whether to include external domain links in the final results.
- include_images boolean(default false) - Whether to include images in the crawl results.
- extract_depth "basic"|"advanced" (default "basic") - Extraction quality level.
basiccosts 1 credit per 5 extractions;advancedcosts 2 credits per 5.
- format "markdown"|"text" (default "markdown") - Content format of extracted pages.
textmay increase latency.
- include_favicon boolean(default false) - Whether to include the favicon URL for each result.
- timeout decimal(default 150) - Maximum time in seconds before timeout.
- include_usage boolean(default false) - Whether to include credit usage information in the response.
tavily: CrawlResponse
Fields
- base_url? string - The base URL that was crawled.
- results? CrawlResult[] - A list of extracted content from the crawled URLs.
- response_time? float - Time in seconds it took to complete the request.
- usage? Usage - Credit usage details, included when
include_usageis true.
- request_id? string - A unique request identifier you can share with customer support.
tavily: CrawlResult
Fields
- url? string - The URL that was crawled.
- raw_content? string - The full content extracted from the page. When
instructionsare provided, contains the top-ranked chunks joined by[...].
- favicon? string - The favicon URL, if
include_faviconwas requested.
tavily: CreateResearchHeaders
Represents the Headers record for the operation: createResearch
Fields
- X\-Session\-Id? string - Optional session identifier for grouping related requests in analytics.
- X\-Human\-Id? string - Optional identifier for the end user driving the request.
- X\-Project\-ID? string - Optional project ID to scope the request to a specific project.
tavily: ExtractHeaders
Represents the Headers record for the operation: extract
Fields
- X\-Session\-Id? string - Optional session identifier for grouping related requests in analytics.
- X\-Human\-Id? string - Optional identifier for the end user driving the request.
- X\-Project\-ID? string - Optional project ID to scope the request to a specific project.
tavily: ExtractRequest
Fields
- query? string - User intent used to rerank extracted content chunks by relevance.
- chunks_per_source int(default 3) - Maximum relevant chunks per source. Only available when
queryis set.
- extract_depth "basic"|"advanced" (default "basic") - Extraction level.
advancedretrieves more data, including tables and embedded content.
- include_images boolean(default false) - Include a list of extracted image URLs in the response.
- include_favicon boolean(default false) - Include the favicon URL for each result.
- format "markdown"|"text" (default "markdown") - The format of the extracted content.
- timeout? float - Maximum time in seconds to wait for extraction. Defaults to 10s for
basicand 30s foradvanced.
- include_usage boolean(default false) - Include credit usage information in the response.
tavily: ExtractResponse
Fields
- results? ExtractResult[] - Extracted content from the provided URLs.
- failed_results? FailedResult[] - URLs that could not be processed.
- response_time? float - Time in seconds it took to complete the request.
- usage? Usage - Credit usage details, included when
include_usageis true.
- request_id? string - A unique request identifier you can share with customer support.
tavily: ExtractResult
Fields
- url? string - The source URL.
- raw_content? string - The full extracted page content. When
queryis provided, contains the top-ranked chunks joined by[...].
- images? string[] - Extracted image URLs, if
include_imageswas requested.
- favicon? string - The favicon URL, if
include_faviconwas requested.
tavily: FailedResult
Fields
- url? string - The URL that failed.
- 'error? string - A description explaining the failure.
tavily: GetUsageHeaders
Represents the Headers record for the operation: getUsage
Fields
- X\-Project\-ID? string - Optional project ID to scope the request to a specific project.
tavily: KeyUsage
Fields
- usage? int - Total credits used by this API key.
- 'limit? int? - The credit limit for this key, or null if unlimited.
- search_usage? int - Credits used by search requests.
- extract_usage? int - Credits used by extract requests.
- crawl_usage? int - Credits used by crawl requests.
- map_usage? int - Credits used by map requests.
- research_usage? int - Credits used by research requests.
tavily: MapHeaders
Represents the Headers record for the operation: map
Fields
- X\-Session\-Id? string - Optional session identifier for grouping related requests in analytics.
- X\-Human\-Id? string - Optional identifier for the end user driving the request.
- X\-Project\-ID? string - Optional project ID to scope the request to a specific project.
tavily: MapRequest
Fields
- url string - The root URL to begin the mapping.
- instructions? string? - Natural language guidance for the crawler. Increases cost to 2 credits per 10 successful pages.
- max_depth int(default 1) - Max depth of the mapping.
- max_breadth int(default 20) - Max number of links to follow per level of the tree.
- 'limit int(default 50) - Total number of links the crawler will process before stopping.
- select_paths? string[]? - Regex patterns to select only URLs with specific path patterns.
- select_domains? string[]? - Regex patterns to restrict mapping to specific domains or subdomains.
- exclude_paths? string[]? - Regex patterns to exclude URLs with specific path patterns.
- exclude_domains? string[]? - Regex patterns to exclude specific domains from mapping.
- allow_external boolean(default true) - Whether to include external domain links in the results.
- timeout float(default 150) - Maximum time in seconds to wait.
- include_usage boolean(default false) - Whether to include credit usage information in the response.
tavily: MapResponse
Fields
- base_url? string - The mapped starting URL.
- results? string[] - A list of URLs that were discovered during mapping.
- response_time? float - Time in seconds it took to complete the request.
- usage? Usage - Credit usage details, included when
include_usageis true.
- request_id? string - A unique request identifier you can share with customer support.
tavily: ResearchFile
Fields
- name string - The filename, including its extension.
- data string - The base64-encoded file contents.
- 'type string(default "base64") - The encoding type of the file data.
tavily: ResearchRequest
Fields
- input string - The research task or question to investigate.
- model "mini"|"pro"|"auto" (default "auto") - Research agent model.
miniis targeted and efficient;prois comprehensive;autoselects automatically.
- 'stream boolean(default false) - Whether to stream the research results as Server-Sent Events.
- output_schema? record {}? - JSON Schema defining the structure of the output. Requires a
propertiesfield and an optionalrequiredfield.
- citation_format "numbered"|"mla"|"apa"|"chicago" (default "numbered") - The citation style used in the report.
- include_domains string[](default []) - Soft preference for sources. The agent prioritizes but is not limited to these domains.
- exclude_domains string[](default []) - Hard blocklist of domains and subdomains to avoid.
- output_length "short"|"standard"|"long" (default "standard") - Target size of the response.
- files? ResearchFile[] - Up to 5 files (.txt, .md, .json) to include as context. Max 80,000 words per file and 80,000 words combined.
tavily: ResearchSource
Fields
- title? string - Title or name of the source.
- url? string - URL of the source.
- favicon? string - URL to the source's favicon.
tavily: ResearchTaskCompleted
Fields
- request_id? string - The task identifier.
- created_at? string - Timestamp when the task was created (ISO 8601).
- status? "completed" - The task status.
- content? string|record {} - The research report content. A string, or a structured object when
output_schemawas provided.
- sources? ResearchSource[] - The list of sources used in the research.
- response_time? int - Seconds to complete the request.
tavily: ResearchTaskCreated
Fields
- request_id? string - A unique identifier for the research task.
- created_at? string - Timestamp when the research task was created (ISO 8601).
- status? string - The current status of the task.
- input? string - The research question submitted.
- model? string - The model used by the research agent.
- response_time? float - Processing time in seconds.
tavily: ResearchTaskFailed
Fields
- request_id? string - The task identifier.
- status? "failed" - The task status.
- response_time? int - Seconds elapsed.
tavily: ResearchTaskPending
Fields
- request_id? string - The task identifier.
- status? "pending"|"in_progress" - The current status of the task.
- response_time? int - Seconds elapsed.
tavily: SearchHeaders
Represents the Headers record for the operation: search
Fields
- X\-Session\-Id? string - Optional session identifier for grouping related requests in analytics.
- X\-Human\-Id? string - Optional identifier for the end user driving the request.
- X\-Project\-ID? string - Optional project ID to scope the request to a specific project.
tavily: SearchImage
Fields
- url? string - The image URL.
- description? string - Descriptive text, if
include_image_descriptionswas requested.
tavily: SearchRequest
Fields
- query string - The search query to execute.
- search_depth "basic"|"advanced"|"fast"|"ultra-fast" (default "basic") - Controls the trade-off between latency and relevance.
advancedcosts 2 credits;basic,fast, andultra-fastcost 1 credit.
- chunks_per_source int(default 3) - Maximum number of relevant content chunks returned per source. Available only when
search_depthisadvanced.
- max_results int(default 5) - Maximum number of search results to return.
- topic "general"|"news" (default "general") - The category of the search.
- time_range? "day"|"week"|"month"|"year"|"d"|"w"|"m"|"y"? - Filter results by a relative time range from the current date.
- start_date? string? - Return results published after this date (YYYY-MM-DD).
- end_date? string? - Return results published before this date (YYYY-MM-DD).
- include_answer boolean|"basic"|"advanced" (default false) - Include an LLM-generated answer.
true/basicreturns a quick answer;advancedreturns a more detailed answer.
- include_raw_content boolean|"markdown"|"text" (default false) - Include the cleaned page content for each result.
true/markdownreturns markdown;textreturns plain text.
- include_images boolean(default false) - Include a list of query-related images in the response.
- include_image_descriptions boolean(default false) - Add descriptive text for each image. Requires
include_images: true.
- include_favicon boolean(default false) - Include the favicon URL for each result.
- include_domains string[](default []) - A list of domains to specifically include in the results.
- exclude_domains string[](default []) - A list of domains to specifically exclude from the results.
- country? string? - Boost results from a specific country. Only available with the
generaltopic.
- auto_parameters boolean(default false) - Automatically configure search parameters based on the query intent. Costs 2 credits.
- exact_match boolean(default false) - Return only results matching exact quoted phrases in the query.
- include_usage boolean(default false) - Include credit usage information in the response.
- safe_search boolean(default false) - Filter out adult or unsafe content. Enterprise only; not available with
fastorultra-fastsearch depth.
tavily: SearchResponse
Fields
- query? string - The executed search query.
- answer? string - The LLM-generated answer, if
include_answerwas requested.
- images? SearchImage[] - Query-related images, if
include_imageswas requested.
- results? SearchResult[] - Ranked search results.
- auto_parameters? record {} - The parameters selected automatically, if
auto_parameterswas enabled.
- response_time? float - Time in seconds it took to complete the request.
- usage? Usage - Credit usage details, included when
include_usageis true.
- request_id? string - A unique request identifier you can share with customer support.
tavily: SearchResult
Fields
- title? string - The title of the result.
- url? string - The URL of the result.
- content? string - A short description of the result relevant to the query.
- score? float - The relevance score of the result.
- raw_content? string? - The cleaned page content, if
include_raw_contentwas requested.
- favicon? string - The favicon URL, if
include_faviconwas requested.
- images? string[] - Images from this result, if
include_imageswas requested.
tavily: Usage
Credit usage details, included when include_usage is true.
Fields
- credits? int - The number of credits consumed by the request.
tavily: UsageResponse
Fields
- 'key? KeyUsage -
- account? AccountUsage -
Import
import ayesha/tavily;Metadata
Released date: 4 months ago
Version: 0.5.0
License: Apache-2.0
Security
Direct vulnerabilities: No known direct vulnerabilities
Indirect vulnerabilities:
Checked on 2026-11-15 via OSV.dev
Compatibility
Platform: any
Ballerina version: 2201.13.0
GraalVM compatible: Yes
Pull count
Total: 0
Current verison: 0
Weekly downloads
Keywords
ai
search
web-search
research