Skip to main content
POST
Python SDK

Authorizations

​
Authorization
string
header
required

Bearer authentication header in the form Bearer , where is your Tavily API key (e.g., Bearer tvly-YOUR_API_KEY).

Body

application/json

Parameters for the Tavily Crawl request.

​
url
string
required

The root URL to begin the crawl.

Example:

"docs.tavily.com"

​
instructions
string

Natural language instructions for the crawler. When specified, the mapping cost increases to 2 API credits per 10 successful pages instead of 1 API credit per 10 pages.

Example:

"Find all pages about the Python SDK"

​
chunks_per_source
integer
default:3

Chunks are short content snippets (about 800 characters each) pulled directly from the source. Use chunks_per_source to define the maximum number of relevant chunks returned per source and to control the raw_content length. Chunks will appear in the raw_content field as: <chunk 1> [...] <chunk 2> [...] <chunk 3>. If a page splits into no more chunks than chunks_per_source, its full content is returned. Available only when instructions are provided. Must be between 1 and 5.

Required range: 1 <= x <= 5
​
max_depth
integer
default:1

Max depth of the crawl. Defines how far from the base URL the crawler can explore.

Required range: 1 <= x <= 5
​
max_breadth
integer
default:20

Max number of links to follow per level of the tree (i.e., per page).

Required range: 1 <= x <= 500
​
limit
integer
default:50

Total number of links the crawler will process before stopping.

Required range: x >= 1
​
select_paths
string[]

Regex patterns to select only URLs with specific path patterns (e.g., /docs/.*, /api/v1.*).

​
select_domains
string[]

Regex patterns to select crawling to specific domains or subdomains (e.g., ^docs\.example\.com$).

​
exclude_paths
string[]

Regex patterns to exclude URLs with specific path patterns (e.g., /private/.*, /admin/.*).

​
exclude_domains
string[]

Regex patterns to exclude specific domains or subdomains from crawling (e.g., ^private\.example\.com$).

​
allow_external
boolean
default:true

Whether to include external domain links in the final results list.

​
include_images
boolean
default:false

Whether to include images in the crawl results.

​
extract_depth
enum<string>
default:basic

Advanced extraction retrieves more data, including tables and embedded content, with higher success but may increase latency. basic extraction costs 1 credit per 5 successful extractions, while advanced extraction costs 2 credits per 5 successful extractions.

Available options:
basic,
advanced
​
format
enum<string>
default:markdown

The format of the extracted web page content. markdown returns content in markdown format. text returns plain text and may increase latency.

Available options:
markdown,
text
​
include_favicon
boolean
default:false

Whether to include the favicon URL for each result.

​
timeout
number<float>
default:150

Maximum time in seconds to wait for the crawl operation before timing out. Must be between 10 and 150 seconds.

Required range: 10 <= x <= 150
​
include_usage
boolean
default:false

Whether to include credit usage information in the response. NOTE:The value may be 0 if the total use of /extract and /map have not yet reached minimum requirements. See our Credits & Pricing documentation for details.

Response

Crawl results returned successfully

​
base_url
string

The base URL that was crawled.

Example:

"docs.tavily.com"

​
results
object[]

A list of extracted content from the crawled URLs.

Example:
​
response_time
number<float>

Time in seconds it took to complete the request.

Example:

1.23

​
usage
object

Credit usage details for the request.

Example:
​
request_id
string

A unique request identifier you can share with customer support to help resolve issues with specific requests.

Example:

"123e4567-e89b-12d3-a456-426614174111"