Una página, o todas.

La superficie de crawl son tres llamadas que crecen con el trabajo: una página, un mapa de las URL, o todas las páginas dentro de un alcance que tú fijas. Guarda el alcance y se vuelve invocable — POST /api/crawl/definitions/{ref}/run responde desde la última ejecución si está lo bastante fresca, y vuelve a crawlear si no.

superficies ▸ tres tamaños

Tres llamadas, tres tamaños de trabajo.

Usa la más pequeña que responda tu pregunta. Una sola página es una página medida; un mapa es una lista de URL; un crawl recorre el alcance y llena un dataset que puedes leer, buscar y exportar.

Una página, dos niveles

Con una clave wt_ la llamada se mide contra tu plan. Sin clave alguna, el nivel keyless devuelve la misma forma para páginas públicas — más abajo. El nivel sin clave también rastrea: POST /v1/keyless/crawl carga hasta 5 páginas del mismo dominio, un nivel de profundidad, y las devuelve en línea — sin flota, sin persona, sin salida residencial. Cada página gasta la misma asignación diaria que una llamada a <code>/v1/keyless/scrape</code>: el tope diario, no el de la petición, es el límite real, y la respuesta indica ambos.

const cloud = new CloudApi({ apiKey: process.env.WRIT_API_KEY }); // wt_…
const page = await cloud.scrape("https://example.com");
const site = await cloud.map("https://example.com", { search: "pricing", limit: 20 });
console.log(cloud.tier); // "metered" | "keyless"

cloud = Cloud(api_key=os.environ["WRIT_API_KEY"])  # wt_… — no daemon needed
page = cloud.scrape("https://example.com")
site = cloud.map("https://example.com", search="pricing", limit=20)
print(cloud.tier)  # "metered" | "keyless"

# Metered — wt_ API key, billed from your credit pool
curl -X POST https://api.usewrit.app/api/crawl/scrape \
  -H "Authorization: Bearer $WRIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'

# Keyless — no account, no key: a stable device id is the only identity.
# 429 keyless_rate_limited when the allowance is spent.
curl -X POST https://api.usewrit.app/v1/keyless/scrape \
  -H "X-Writ-Client-Id: $WRIT_CLIENT_ID" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'
curl https://api.usewrit.app/v1/keyless/quota -H "X-Writ-Client-Id: $WRIT_CLIENT_ID"

Qué devuelve una página

La llamada de una página devuelve un cuerpo plano, no un handle de job:

alcance ▸ qué se carga

Di qué crawlear, y hasta dónde.

Solo url es obligatorio. Todo lo demás estrecha el alcance, cambia cómo se lee una página, o pone tope al trabajo. Los filtros de ruta son expresiones regulares aplicadas a la ruta.

Iniciar un crawl

En el agente local el mismo job arranca en 127.0.0.1:8131 con un token local, y el dataset que llena se relee por la superficie de datos.

const job = await client.crawl.start({
  url: "https://example.com",
  max_depth: 3,
  page_budget: 500,
});
const status = await client.crawl.get(job.id);
const table = await client.data.workflowData(job.data_workflow_id);

job = client.crawl.start("https://example.com", max_depth=3, page_budget=500)
job = client.crawl.get(job["id"])
table = client.data.workflow_data(job["data_workflow_id"])

job, _ := client.Crawl.Start(ctx, writ.CrawlStartParams{URL: "https://example.com"})
st, _ := client.Crawl.Get(ctx, job.ID)

use writ_client::CrawlStartParams;

let job = agent.crawl().start(CrawlStartParams {
    url: "https://example.com".into(),
    ..Default::default()
}).await?;
let job = agent.crawl().get(job.id).await?;

progreso ▸ estado

Míralo trabajar. Párala cuando quieras.

Un crawl es un job, no una petición: sobrevive con normalidad a cualquier timeout HTTP sensato, así que recibes un handle y lo consultas. GET /v1/crawl los lista (limit 1–500, 50 por defecto) bajo una clave crawls; GET /v1/crawl/{id} lee uno, o 404 si no es tuyo.

Los contadores de un crawl

Cada lectura de un crawl lleva los mismos campos, así que un solo consultador sirve para todos los sitios de ejecución:

guardado ▸ invocable

Guarda un crawl y llámalo como una API.

Una definición es una configuración de crawl con nombre y slug. Convierte un job puntual en algo que una clave puede llamar: /v1/crawl/definitions en el agente local, /api/crawl/definitions en Writ Cloud. Ambos aceptan un slug o un id como {ref}.

Ejecutarla

El cuerpo de ejecución son cuatro campos, todos opcionales:

El contrato de frescura

Esta es la parte contra la que programar. El código de estado dice qué pasó, y ninguna respuesta es un callejón sin salida:

Guardar, llamar, leer

Tres llamadas: crear la definición, ejecutarla con una ventana, leer lo que ya contiene.

# 1. Save the crawl — name + slug + the config it should always run.
curl -X POST https://api.usewrit.app/api/crawl/definitions \
  -H "Authorization: Bearer $WRIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Docs index",
    "slug": "docs-index",
    "default_max_age_seconds": 86400,
    "config": {
      "url": "https://example.com/docs",
      "include_paths": ["^/docs/"],
      "max_depth": 3,
      "page_budget": 500
    }
  }'

# 2. Call it. Fresh enough? You get the data. Stale? It re-crawls.
curl -X POST https://api.usewrit.app/api/crawl/definitions/docs-index/run \
  -H "Authorization: Bearer $WRIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"max_age": 86400, "wait": true, "timeout": 120, "limit": 50}'

{
  "cached": true,
  "_cache": { "hit": true, "age_seconds": 3512, "source_crawl_id": 8811 },
  "definition": { "name": "Docs index", "slug": "docs-index" },
  "crawl": { "id": 8811, "status": "completed", "pages_done": 412 },
  "status_url": "/api/crawl/8811",
  "data": [ { "url": "https://example.com/docs/intro", "title": "Intro" } ]
}

// A miss answers 202 with the new crawl and its status_url instead.
// wait:true that overruns answers 504 — still carrying crawl_id and
// status_url, so the pages already paid for stay collectable.

# What the last completed run collected — any age, never crawls, never bills.
curl "https://api.usewrit.app/api/crawl/definitions/docs-index/data?limit=50" \
  -H "Authorization: Bearer $WRIT_API_KEY"

# Force a fresh pass, whatever the definition's default window says.
curl -X POST https://api.usewrit.app/api/crawl/definitions/docs-index/run \
  -H "Authorization: Bearer $WRIT_API_KEY" \
  -H "Cache-Control: no-cache"

documentos ▸ ocr

PDF, hojas de cálculo y páginas escaneadas.

Un sitio rara vez es solo HTML. Los PDF, los archivos de Word, Excel y PowerPoint, las imágenes y las páginas escaneadas se leen dentro del crawl, con OCR donde el texto son solo píxeles. Lo gobierna un único mando:

precio ▸ por página

Una página cuesta $0,0005. Algunas pesan más.

El crawl se paga por uso, por página. Dentro de las páginas de crawl mensuales de tu plan no cuesta nada extra; por encima se cobra del wallet a la misma tarifa, y un wallet que no cubre la página responde 402 insufficient_credits. Los despliegues autoalojados rastrean con tus propios agentes y no llevan ningún cargo por página por nuestra parte.

Qué incluye cada plan

Tres números distintos por plan. Léelos como tres, no como uno — responden a tres preguntas diferentes.

También fallan de forma distinta. Un page_budget mayor que tu tope por crawl se recorta al tope y el crawl se ejecuta — no se te rechaza por pedirlo. Las dos barreras que sí pueden negarse son el límite de concurrencia (un crawl de más mientras otros corren) y la asignación mensual una vez que el wallet no cubre el exceso.

Leer el contador

GET /api/crawl/meta/usage devuelve tu posición actual, para que un cliente decida antes de gastar:

curl https://api.usewrit.app/api/crawl/meta/usage \
  -H "Authorization: Bearer $WRIT_API_KEY"

{
  "pages_included_per_month": 75000,
  "pages_used_this_period": 12480,
  "pages_remaining": 62520,
  "per_job_page_cap": 25000,
  "max_concurrent_crawls": 3,
  "overage_price_micros_per_page": 500,
  "browser_page_units": 2,
  "ocr_page_units": 2
}

// -1 anywhere in this body means unlimited.

keyless ▸ sin cuenta

¿Sin cuenta? Una página cada vez.

El nivel keyless lee páginas públicas sin cuenta y sin clave. Un dispositivo se identifica por una cabecera de id de cliente, y la asignación es pequeña a propósito: existe para que un SDK o la app de escritorio funcione antes de registrarte.

Los topes

• 10 peticiones y 20 páginas al día, por dispositivo.
• 30 peticiones al día y 10 por minuto, por dirección IP.
• Un mapa devuelve como mucho 200 URL.
• Al pasarse de cualquiera: 429 keyless_rate_limited.

claves ▸ scopes

Tres scopes, desiguales a propósito.

Leer una página es algo más pequeño que crawlear un sitio, así que es un scope más pequeño. Una clave entregada a un socio para lecturas de una página no puede iniciar un crawl contra tu asignación.

mcp ▸ herramientas

El mismo crawl, como herramientas MCP.

El servidor MCP de escritorio expone la superficie de crawl como herramientas, para que un cliente de IA lance y relance un crawl sin que tú escribas nada de HTTP:

// Crawl a site and save it under a callable name in one turn.
writ_crawl_site {
  "url": "https://example.com/docs",
  "extract": "markdown",
  "max_pages": 500,
  "max_depth": 3,
  "include": ["^/docs/"],
  "exclude": ["^/docs/legacy/"],
  "same_domain": true,
  "allow_subdomains": false,
  "content": { "preset": "article", "exclude_selectors": ["nav", "footer"] },
  "save_as": "docs-index"
}

// Re-using a save_as name UPDATES that saved crawl — it does not duplicate it.
// max_age only matters together with save_as.
writ_run_saved_crawl { "crawl": "docs-index", "max_age": 86400, "limit": 50 }
writ_saved_crawl_data { "crawl": "docs-index" }
writ_saved_crawls {}
writ_crawl_status { "crawl_id": 8811 }
writ_map  { "url": "https://example.com" }
writ_scrape { "url": "https://example.com/pricing" }

referencia ▸ siguiente

Adónde va el crawl después

faq

Preguntas de crawl, respondidas.

fin ▸ lanzar uno

Previsualiza el alcance y lánzalo.

El preview no cuesta nada y muestra exactamente qué URL conservaría un crawl. Es la forma más barata de asegurarte antes de un presupuesto de páginas grande.