curl --request POST \
--url https://tavusapi.com/v2/documents/{document_id}/recrawl \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"crawl": {
"depth": 3,
"max_pages": 50
}
}
'import requests
url = "https://tavusapi.com/v2/documents/{document_id}/recrawl"
payload = { "crawl": {
"depth": 3,
"max_pages": 50
} }
headers = {
"x-api-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({crawl: {depth: 3, max_pages: 50}})
};
fetch('https://tavusapi.com/v2/documents/{document_id}/recrawl', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://tavusapi.com/v2/documents/{document_id}/recrawl",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'crawl' => [
'depth' => 3,
'max_pages' => 50
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"x-api-key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://tavusapi.com/v2/documents/{document_id}/recrawl"
payload := strings.NewReader("{\n \"crawl\": {\n \"depth\": 3,\n \"max_pages\": 50\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-api-key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://tavusapi.com/v2/documents/{document_id}/recrawl")
.header("x-api-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"crawl\": {\n \"depth\": 3,\n \"max_pages\": 50\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://tavusapi.com/v2/documents/{document_id}/recrawl")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"crawl\": {\n \"depth\": 3,\n \"max_pages\": 50\n }\n}"
response = http.request(request)
puts response.read_body{
"document_id": "d8-5c71baca86fc",
"document_name": "Company Website",
"document_url": "https://example.com/",
"status": "recrawling",
"progress": null,
"error_message": "<string>",
"created_at": "2024-01-01T12:00:00Z",
"updated_at": "2024-01-15T10:30:00Z",
"callback_url": "https://your-server.com/webhook",
"tags": [
"website",
"company"
],
"crawl_config": {
"depth": 2,
"max_pages": 10
},
"crawled_urls": [
"https://docs.example.com/",
"https://docs.example.com/getting-started"
],
"last_crawled_at": "2024-01-01T12:05:00Z",
"crawl_count": 1
}{
"error": "Document was not created with crawl configuration"
}{
"message": "Invalid access token"
}{
"message": "Document not found"
}{
"error": "Document must be in 'ready' or 'error' state to recrawl, current status: processing"
}{
"error": "Recrawl cooldown: please wait 45 minutes before recrawling this document."
}Recrawl Document
Trigger a recrawl of a website document to fetch fresh content.
curl --request POST \
--url https://tavusapi.com/v2/documents/{document_id}/recrawl \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"crawl": {
"depth": 3,
"max_pages": 50
}
}
'import requests
url = "https://tavusapi.com/v2/documents/{document_id}/recrawl"
payload = { "crawl": {
"depth": 3,
"max_pages": 50
} }
headers = {
"x-api-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({crawl: {depth: 3, max_pages: 50}})
};
fetch('https://tavusapi.com/v2/documents/{document_id}/recrawl', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://tavusapi.com/v2/documents/{document_id}/recrawl",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'crawl' => [
'depth' => 3,
'max_pages' => 50
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"x-api-key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://tavusapi.com/v2/documents/{document_id}/recrawl"
payload := strings.NewReader("{\n \"crawl\": {\n \"depth\": 3,\n \"max_pages\": 50\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-api-key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://tavusapi.com/v2/documents/{document_id}/recrawl")
.header("x-api-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"crawl\": {\n \"depth\": 3,\n \"max_pages\": 50\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://tavusapi.com/v2/documents/{document_id}/recrawl")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"crawl\": {\n \"depth\": 3,\n \"max_pages\": 50\n }\n}"
response = http.request(request)
puts response.read_body{
"document_id": "d8-5c71baca86fc",
"document_name": "Company Website",
"document_url": "https://example.com/",
"status": "recrawling",
"progress": null,
"error_message": "<string>",
"created_at": "2024-01-01T12:00:00Z",
"updated_at": "2024-01-15T10:30:00Z",
"callback_url": "https://your-server.com/webhook",
"tags": [
"website",
"company"
],
"crawl_config": {
"depth": 2,
"max_pages": 10
},
"crawled_urls": [
"https://docs.example.com/",
"https://docs.example.com/getting-started"
],
"last_crawled_at": "2024-01-01T12:05:00Z",
"crawl_count": 1
}{
"error": "Document was not created with crawl configuration"
}{
"message": "Invalid access token"
}{
"message": "Document not found"
}{
"error": "Document must be in 'ready' or 'error' state to recrawl, current status: processing"
}{
"error": "Recrawl cooldown: please wait 45 minutes before recrawling this document."
}https://docs.tavus.io/openapi.yaml for the full HTTP API contract.Path Parameters
Unique id of the crawl-backed website document to refresh. Use when the source site changed, you want to refresh content on a schedule, or retry after crawl or processing errors.
The document must be in ready or error (otherwise 409). It must have been created with a crawl configuration unless you supply crawl in the request body for this call.
The same document cannot be recrawled more than once within each 1-hour cooldown (429 if invoked too soon).
Body
Optional body. Omit entirely to reuse the crawl depth / max_pages stored from document creation, or include crawl to override those values for this run only.
After 202, status is typically recrawling until processing finishes. If you set callback_url when creating the document, webhooks report progress until the document returns to ready or error.
Poll Get Document for current status, crawl_count, and last_crawled_at.
Account limits: at most 5 concurrent crawls per user and at most 10,000 crawl-backed documents per user.
Optional depth and max_pages for this recrawl only; overrides stored crawl settings from document creation when provided. If omitted, the original crawl configuration is used.
What runs: the same starting URL as the original crawl, links followed within these limits, fresh page content processed, existing vectors replaced when processing completes, and crawl_count / last_crawled_at updated (see the 202 payload and Get Document while status is recrawling).
Show child attributes
Show child attributes
Response
Recrawl initiated successfully
Error code indicating why processing failed. Only present when status is error. Possible values include: file_download_failed, file_format_unsupported, file_size_too_large, file_empty, invalid_file_url, document_processing_failed, website_processing_failed, chunking_failed, embedding_failed, vector_store_failed, contact_support.
If set on Create Document, Tavus POSTs status updates here while this recrawl runs through completion.
"https://your-server.com/webhook"

