---
title: "Recrawl Document"
method: POST
path: "/v2/documents/{document_id}/recrawl"
tags: ["Documents"]
---

# Recrawl Document

`POST /v2/documents/{document_id}/recrawl`

Trigger a recrawl of a website document to fetch fresh content.

## Path parameters

- `document_id` string, required

## Request body

- object
  - `crawl` object — 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`).
    - `depth` integer — How many levels deep to follow links from the starting URL (1-10). A depth of 1 means only pages directly linked from the starting URL.
    - `max_pages` integer — Maximum number of pages to crawl (1-100). Processing stops once this limit is reached.

## Response `202`

Recrawl initiated successfully

- object
  - `document_id` string — Unique identifier for the document
  - `document_name` string — Name of the document
  - `document_url` string — URL of the document
  - `status` 'started' | 'processing' | 'ready' | 'error' | 'recrawling' — After a successful recrawl request, typically **`recrawling`** until processing completes, then **`ready`** or **`error`**. Other values: `started`, `processing`.
  - `progress` integer, nullable — Processing progress as a percentage (0-100). Null when processing has not started or is complete.
  - `error_message` string, nullable — 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`.
  - `created_at` string — ISO 8601 timestamp of when the document was created
  - `updated_at` string — ISO 8601 timestamp of when the document was last updated
  - `callback_url` string — If set on [Create Document](/api-reference/documents/create-document), Tavus POSTs status updates here while this recrawl runs through completion.
  - `tags` string[] — Array of document tags
  - `crawl_config` object — The crawl configuration being used for the recrawl
    - `depth` integer
    - `max_pages` integer
  - `crawled_urls` string[], nullable — List of URLs from the previous crawl (will be updated when recrawl completes)
  - `last_crawled_at` string, nullable — ISO 8601 timestamp of the previous crawl
  - `crawl_count` integer — Number of times the document has been crawled (will increment when recrawl completes)

## Other responses

- `400` — Bad Request - Validation error
- `401` — Unauthorized
- `404` — Not Found
- `409` — Conflict - Document state prevents recrawl
- `429` — Too Many Requests - Rate limit exceeded or cooldown period

---

[API](https://skmtc.dev/tavus/apis/tavus-developer-api-collection.md) · [All operations](https://skmtc.dev/tavus/apis/tavus-developer-api-collection/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/tavus/tavus-developer-api-collection/revisions/c878e2f6508d/schema)