Une page, ou toutes les pages.

La surface de crawl tient en trois appels qui grandissent avec le travail : une page, une carte des URL, ou toutes les pages d’un périmètre que vous fixez. Enregistrez le périmètre et il devient appelable — POST /api/crawl/definitions/{ref}/run répond depuis la dernière exécution si elle est assez fraîche, et recrawle sinon.

surfaces ▸ trois tailles

Trois appels, trois tailles de travail.

Prenez le plus petit qui répond à votre question. Une page seule vaut une page décomptée ; une carte est une liste d’URL ; un crawl parcourt le périmètre et remplit un dataset que vous pouvez lire, fouiller et exporter.

Une page, deux paliers

Avec une clé wt_, l’appel est décompté de votre plan. Sans aucune clé, le palier keyless rend la même forme pour les pages publiques — voir plus bas. Le palier sans clé crawle aussi : POST /v1/keyless/crawl charge jusqu’à 5 pages du même domaine, sur un niveau, et les rend en ligne — sans flotte, sans persona, sans sortie résidentielle. Chaque page consomme la même allocation quotidienne qu’un appel à <code>/v1/keyless/scrape</code> : le plafond quotidien, pas celui par requête, est la vraie limite, et la réponse indique les deux.

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"

Ce que rend une page

L’appel une-page rend un corps plat, pas un handle de job :

périmètre ▸ ce qui est chargé

Dites quoi crawler, et jusqu’où.

Seul url est obligatoire. Tout le reste resserre le périmètre, change la façon de lire une page, ou plafonne le travail. Les filtres de chemin sont des expressions régulières appliquées au chemin.

Démarrer un crawl

Sur l’agent local, le même job démarre sur 127.0.0.1:8131 avec un token local, et le dataset qu’il remplit se relit par la surface de données.

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?;

avancement ▸ statut

Regardez-le travailler. Arrêtez-le quand vous voulez.

Un crawl est un job, pas une requête : il survit couramment à tout timeout HTTP raisonnable, donc vous recevez un handle et vous l’interrogez. GET /v1/crawl les liste (limit 1–500, 50 par défaut) sous une clé crawls ; GET /v1/crawl/{id} en lit un, ou 404 s’il n’est pas à vous.

Les compteurs d’un crawl

Chaque lecture d’un crawl porte les mêmes champs, donc un seul poller couvre tous les lieux d’exécution :

enregistré ▸ appelable

Enregistrez un crawl, puis appelez-le comme une API.

Une définition est une configuration de crawl avec un nom et un slug. Elle transforme un job ponctuel en quelque chose qu’une clé peut appeler : /v1/crawl/definitions sur l’agent local, /api/crawl/definitions sur Writ Cloud. Les deux acceptent un slug ou un id comme {ref}.

L’exécuter

Le corps d’exécution tient en quatre champs, tous facultatifs :

Le contrat de fraîcheur

C’est la partie contre laquelle coder. Le code de statut dit ce qui s’est passé, et aucune réponse n’est une impasse :

Enregistrer, appeler, relire

Trois appels : créer la définition, l’exécuter avec une fenêtre, lire ce qu’elle contient déjà.

# 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"

documents ▸ ocr

PDF, tableurs et pages scannées.

Un site est rarement du HTML seul. Les PDF, les fichiers Word, Excel et PowerPoint, les images et les pages scannées sont lus dans le cadre du crawl, avec OCR là où le texte n’est que des pixels. Un seul bouton le règle :

prix ▸ à la page

Une page vaut 0,0005 $. Certaines pèsent plus.

Le crawl se paie à l’usage, à la page. Dans les pages de crawl mensuelles de votre plan, cela ne coûte rien de plus ; au-delà, c’est prélevé sur le wallet au même tarif, et un wallet qui ne peut pas couvrir la page répond 402 insufficient_credits. Les déploiements auto-hébergés crawlent sur vos propres agents et ne portent aucun frais de page de notre part.

Ce que chaque plan inclut

Trois nombres distincts par plan. Lisez-les comme trois, pas comme un — ils répondent à trois questions différentes.

Ils échouent aussi différemment. Un page_budget plus grand que votre plafond par crawl est ramené au plafond et le crawl s’exécute — on ne vous refuse pas d’avoir demandé. Les deux barrières qui peuvent vraiment refuser sont la limite de simultanéité (un crawl de trop pendant que d’autres tournent) et l’allocation mensuelle une fois que le wallet ne couvre plus le dépassement.

Lire le compteur

GET /api/crawl/meta/usage rend votre position actuelle, pour qu’un client décide avant de dépenser :

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 ▸ sans compte

Sans compte ? Une page à la fois.

Le palier keyless lit des pages publiques sans compte ni clé. Un appareil est identifié par un en-tête d’identifiant client, et l’allocation est petite à dessein : elle existe pour qu’un SDK ou l’app desktop fonctionne avant l’inscription.

Les plafonds

• 10 requêtes et 20 pages par jour, par appareil.
• 30 requêtes par jour et 10 par minute, par adresse IP.
• Une carte rend au plus 200 URL.
• Au-delà de l’un d’eux : 429 keyless_rate_limited.

clés ▸ scopes

Trois scopes, volontairement inégaux.

Lire une page est une chose plus petite que crawler un site, donc c’est un scope plus petit. Une clé confiée à un partenaire pour des lectures une-page ne peut pas démarrer un crawl sur votre allocation.

mcp ▸ outils

Le même crawl, en outils MCP.

Le serveur MCP desktop expose la surface de crawl en outils, pour qu’un client IA lance et relance un crawl sans que vous écriviez le moindre 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" }

référence ▸ suite

Ce qui vient après le crawl

faq

Questions crawl, répondues.

fin ▸ en lancer un

Prévisualisez le périmètre, puis lancez.

Le preview ne coûte rien et montre exactement quelles URL un crawl garderait. C’est la façon la moins chère d’être sûr avant un gros budget de pages.