AnyCrawl

Tâches planifiées

Automatisez le scraping, le crawl et la recherche récurrents avec des planifications de type cron.

Introduction

Les tâches planifiées permettent d’automatiser le scraping web, le crawl et la collecte de données récurrente à l’aide d’expressions cron standard. Idéal pour la surveillance de sites, le suivi de prix, l’archivage, l’agrégation de résultats de recherche ou toute collecte périodique.

Points clés : planification cron avec fuseau horaire, modes de concurrence, gestion automatique des échecs, crédits, intégration webhooks pour les événements.

Fonctionnalités principales

  • Planification cron : syntaxe cron standard
  • Fuseaux horaires : exécution dans n’importe quel fuseau (ex. Asia/Shanghai, America/New_York)
  • Concurrence : deux modes — ignorer ou mettre en file les exécutions concurrentes
  • Pause automatique : pause après échecs consécutifs pour protéger les ressources
  • Crédits : limite d’exécutions par jour et estimation des crédits
  • Historique : toutes les exécutions avec statut et métriques
  • Webhooks : notifications en temps réel pour les événements de tâche

Points de terminaison de l’API

POST   /v1/scheduled-tasks              # Créer une tâche planifiée
GET    /v1/scheduled-tasks              # Lister les tâches
GET    /v1/scheduled-tasks/:taskId      # Détail d’une tâche
PUT    /v1/scheduled-tasks/:taskId      # Mettre à jour
PATCH  /v1/scheduled-tasks/:taskId/pause   # Mettre en pause
PATCH  /v1/scheduled-tasks/:taskId/resume  # Reprendre
DELETE /v1/scheduled-tasks/:taskId      # Supprimer
GET    /v1/scheduled-tasks/:taskId/executions  # Historique d’exécution
DELETE /v1/scheduled-tasks/:taskId/executions/:executionId  # Annuler une exécution

Démarrage rapide

Créer une tâche de scraping quotidienne

curl -X POST "https://api.anycrawl.dev/v1/scheduled-tasks" \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Daily Tech News",
    "description": "Scrape Hacker News daily at 9 AM",
    "cron_expression": "0 9 * * *",
    "timezone": "Asia/Shanghai",
    "task_type": "scrape",
    "task_payload": {
      "url": "https://news.ycombinator.com",
      "engine": "cheerio",
      "formats": ["markdown"]
    },
    "concurrency_mode": "skip",
    "max_executions_per_day": 1
  }'

Réponse

{
  "success": true,
  "data": {
    "task_id": "550e8400-e29b-41d4-a716-446655440000",
    "next_execution_at": "2026-01-28T01:00:00.000Z"
  }
}

Guide des expressions cron

Les expressions cron utilisent 5 champs :

* * * * *
│ │ │ │ │
│ │ │ │ └─ Jour de la semaine (0-7, 0 et 7 = dimanche)
│ │ │ └─── Mois (1-12)
│ │ └───── Jour du mois (1-31)
│ └─────── Heure (0-23)
└───────── Minute (0-59)

Exemples courants

ExpressionDescriptionExécution
0 9 * * *Chaque jour à 9h0009:00:00 quotidien
*/15 * * * *Toutes les 15 minutes:00, :15, :30, :45
0 */6 * * *Toutes les 6 heures00:00, 06:00, 12:00, 18:00
0 9 * * 1Chaque lundi à 9hLundi 09:00:00
0 0 1 * *Premier jour du moisJour 1, 00:00:00
30 2 * * 0Chaque dimanche à 2h30Dimanche 02:30:00

Utilisez crontab.guru pour valider et comprendre les expressions cron.

Paramètres de requête

Configuration de la tâche

ParamètreTypeObligatoireDéfautDescription
namestringOui-Nom (1–255 caractères)
descriptionstringNon-Description
cron_expressionstringOui-Expression cron standard (5 champs)
timezonestringNon"UTC"Fuseau d’exécution (ex. "Asia/Shanghai")
task_typestringOui-Type : "scrape", "crawl", "search" ou "template"
task_payloadobjectOui-Configuration (voir ci-dessous)

Contrôle de concurrence

ParamètreTypeObligatoireDéfautDescription
concurrency_modestringNon"skip"Mode : "skip" ou "queue"
max_executions_per_daynumberNon-Limite d’exécutions par jour

Métadonnées d’exécution (lecture seule)

Ces champs sont renvoyés dans les réponses de tâche et ne sont pas acceptés dans les corps create/update :

  • min_credits_required : estimation minimale de crédits par exécution (calcul serveur)
  • consecutive_failures : nombre d’échecs consécutifs pour la pause automatique

Intégration webhooks

ParamètreTypeObligatoireDéfautDescription
webhook_idsstring[]Non-UUID d’abonnements webhook à déclencher
webhook_urlstringNon-URL webhook directe (abonnement implicite)

Utilisez webhook_ids pour référencer des abonnements existants, ou webhook_url pour créer un abonnement implicite pour cette tâche.

Métadonnées

ParamètreTypeObligatoireDéfautDescription
tagsstring[]Non-Étiquettes
metadataobjectNon-Métadonnées personnalisées

Charge utile de tâche (task_payload)

Tâche scrape

{
  "url": "https://example.com/page",
  "engine": "cheerio",
  "formats": ["markdown"],
  "timeout": 60000,
  "wait_for": 2000,
  "include_tags": ["article", "main"],
  "exclude_tags": ["nav", "footer"]
}

Tâche crawl

{
  "url": "https://example.com",
  "engine": "playwright",
  "options": {
    "max_depth": 3,
    "limit": 50,
    "strategy": "same-domain",
    "exclude_paths": ["/admin/*", "/api/*"],
    "scrape_options": {
      "formats": ["markdown"]
    }
  }
}
{
  "query": "artificial intelligence news",
  "engine": "google",
  "limit": 20,
  "country": "US",
  "lang": "en",
  "timeRange": "day"
}

Tâche template

{
  "template_id": "my-search-template",
  "query": "machine learning tutorials",
  "variables": {
    "lang": "en"
  }
}

Pour task_type: "template", task_payload doit inclure :

  • template_id (requis) : modèle à exécuter
  • les champs d’entrée requis par le type de modèle (ex. url pour scrape/crawl, query pour search)
  • variables optionnel pour les entrées dynamiques du modèle

Modes de concurrence

skip (recommandé)

Si une exécution précédente est encore en cours, ignorer l’exécution courante.

Idéal pour : tâches dont la durée peut dépasser l’intervalle entre deux exécutions.

Exemple : crawl planifié toutes les heures mais parfois > 90 minutes.

queue

Mettre la nouvelle exécution en file et attendre la fin de la précédente.

Idéal pour : tâches où aucune exécution ne doit être sautée.

Exemple : collecte critique où chaque exécution planifiée doit avoir lieu.

Gestion des tâches

Lister toutes les tâches

curl -X GET "https://api.anycrawl.dev/v1/scheduled-tasks" \
  -H "Authorization: Bearer <your-api-key>"

Réponse

{
  "success": true,
  "data": [
    {
      "uuid": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Daily Tech News",
      "task_type": "scrape",
      "cron_expression": "0 9 * * *",
      "timezone": "Asia/Shanghai",
      "is_active": true,
      "is_paused": false,
      "next_execution_at": "2026-01-28T01:00:00.000Z",
      "total_executions": 45,
      "successful_executions": 43,
      "failed_executions": 2,
      "consecutive_failures": 0,
      "last_execution_at": "2026-01-27T01:00:00.000Z",
      "created_at": "2026-01-01T00:00:00.000Z"
    }
  ]
}

Mettre une tâche en pause

Met une tâche en pause. Le paramètre reason est enregistré comme pause_reason.

curl -X PATCH "https://api.anycrawl.dev/v1/scheduled-tasks/:taskId/pause" \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Maintenance period"
  }'

Réponse

{
  "success": true,
  "message": "Task paused successfully",
  "data": {
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "is_paused": true,
    "pause_reason": "Maintenance period"
  }
}

Reprendre une tâche

curl -X PATCH "https://api.anycrawl.dev/v1/scheduled-tasks/:taskId/resume" \
  -H "Authorization: Bearer <your-api-key>"

Mettre à jour une tâche

curl -X PUT "https://api.anycrawl.dev/v1/scheduled-tasks/:taskId" \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "cron_expression": "0 10 * * *",
    "description": "Updated description"
  }'

Réponse

{
  "success": true,
  "data": {
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Daily Tech News",
    "description": "Updated description",
    "task_type": "scrape",
    "cron_expression": "0 10 * * *",
    "timezone": "Asia/Shanghai",
    "task_payload": {
      "url": "https://news.ycombinator.com",
      "engine": "cheerio",
      "formats": ["markdown"]
    },
    "concurrency_mode": "skip",
    "is_active": true,
    "is_paused": false,
    "next_execution_at": "2026-01-28T02:00:00.000Z",
    "total_executions": 45,
    "successful_executions": 43,
    "failed_executions": 2,
    "consecutive_failures": 0,
    "last_execution_at": "2026-01-27T01:00:00.000Z",
    "created_at": "2026-01-01T00:00:00.000Z",
    "updated_at": "2026-01-27T12:00:00.000Z",
    "icon": "FileText"
  }
}

N’incluez que les champs à modifier. Les autres restent inchangés.

Supprimer une tâche

curl -X DELETE "https://api.anycrawl.dev/v1/scheduled-tasks/:taskId" \
  -H "Authorization: Bearer <your-api-key>"

La suppression supprime aussi tout l’historique d’exécution de la tâche.

Historique d’exécution

Obtenir les exécutions

curl -X GET "https://api.anycrawl.dev/v1/scheduled-tasks/:taskId/executions?limit=20" \
  -H "Authorization: Bearer <your-api-key>"

Réponse

{
  "success": true,
  "data": [
    {
      "uuid": "exec-uuid-1",
      "scheduled_task_uuid": "task-uuid",
      "execution_number": 45,
      "status": "completed",
      "started_at": "2026-01-27T01:00:00.000Z",
      "completed_at": "2026-01-27T01:02:15.000Z",
      "duration_ms": 135000,
      "job_uuid": "job-uuid-1",
      "triggered_by": "scheduler",
      "scheduled_for": "2026-01-27T01:00:00.000Z",
      "error_message": null,
      "credits_used": 5,
      "items_processed": 1,
      "items_succeeded": 1,
      "items_failed": 0,
      "job_status": "completed",
      "job_success": true,
      "icon": "CircleCheck"
    }
  ]
}

Note : Les champs credits_used, items_processed, items_succeeded, items_failed, job_status et job_success proviennent du job associé (JOIN). duration_ms est calculé à partir de started_at et completed_at.

Annuler une exécution

Annule une exécution en attente ou en cours, sans mettre toute la tâche en pause.

curl -X DELETE "https://api.anycrawl.dev/v1/scheduled-tasks/:taskId/executions/:executionId" \
  -H "Authorization: Bearer <your-api-key>"

Réponse

{
  "success": true,
  "message": "Execution cancelled successfully"
}

Seules les exécutions pending ou running peuvent être annulées. Les exécutions terminées, en échec ou déjà annulées renvoient une erreur.

Gestion automatique des échecs

Pause automatique après échecs consécutifs

Les tâches sont mises en pause automatiquement après 5 échecs consécutifs pour limiter la consommation de ressources et d’appels API.

Reprise : reprenez manuellement la tâche après correction du problème.

curl -X PATCH "https://api.anycrawl.dev/v1/scheduled-tasks/:taskId/resume" \
  -H "Authorization: Bearer <your-api-key>"

Suivi des échecs

Utilisez le champ consecutive_failures :

{
  "consecutive_failures": 3,
  "failed_executions": 5,
  "successful_executions": 40
}

Surveillez consecutive_failures. Des valeurs élevées indiquent un problème récurrent.

Intégration avec les webhooks

Abonnez-vous aux événements de tâche via les webhooks :

curl -X POST "https://api.anycrawl.dev/v1/webhooks" \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Task Notifications",
    "webhook_url": "https://your-domain.com/webhook",
    "event_types": ["task.executed", "task.failed", "task.paused"],
    "scope": "all"
  }'

Voir Webhooks pour plus de détails.

Cas d’usage courants

Surveillance de prix

{
  "name": "Hourly Price Tracker",
  "cron_expression": "0 * * * *",
  "task_type": "scrape",
  "task_payload": {
    "url": "https://shop.example.com/product/12345",
    "engine": "cheerio",
    "formats": ["markdown"]
  },
  "concurrency_mode": "skip"
}

Sauvegarde hebdomadaire de documentation

{
  "name": "Weekly Docs Backup",
  "cron_expression": "0 3 * * 0",
  "timezone": "UTC",
  "task_type": "crawl",
  "task_payload": {
    "url": "https://docs.example.com",
    "engine": "playwright",
    "options": {
      "max_depth": 10,
      "limit": 500
    }
  },
  "max_executions_per_day": 1
}

Agrégation d’actualités quotidienne

{
  "name": "Morning News Digest",
  "cron_expression": "0 6 * * *",
  "timezone": "America/New_York",
  "task_type": "scrape",
  "task_payload": {
    "url": "https://news.example.com",
    "engine": "cheerio",
    "formats": ["markdown"]
  },
  "max_executions_per_day": 1
}

Veille concurrentielle

{
  "name": "Competitor Monitoring",
  "cron_expression": "0 * * * *",
  "task_type": "search",
  "task_payload": {
    "query": "YourCompany OR CompetitorA OR CompetitorB",
    "engine": "google",
    "limit": 50,
    "timeRange": "day"
  },
  "concurrency_mode": "skip"
}

Bonnes pratiques

1. Intervalles cron adaptés

  • Évitez les planifications trop fréquentes (< 1 minute) pour limiter les risques de limitation
  • Adaptez l’intervalle à la fréquence de mise à jour du site cible
  • Utilisez le fuseau horaire pour les besoins locaux

2. Mode de concurrence

  • Utilisez "skip" dans la plupart des cas pour éviter le chevauchement
  • Utilisez "queue" uniquement si chaque exécution est critique

3. Crédits

  • Définissez max_executions_per_day pour les tâches coûteuses
  • Consultez min_credits_required dans le détail de la tâche
  • Surveillez la consommation dans l’historique

4. Santé des tâches

  • Vérifiez régulièrement consecutive_failures
  • Analysez l’historique pour détecter des motifs
  • Configurez des webhooks sur les échecs

5. Noms et étiquettes

  • Noms de tâches clairs
  • Tags pour filtrer et organiser
  • Métadonnées pour le suivi

Limites

ÉlémentLimite
Longueur du nom1–255 caractères
Intervalle minimum1 minute
Modes de concurrenceskip, queue
Taille du payload100 Ko
Format cron5 champs standard

Dépannage

La tâche ne s’exécute pas

Vérifiez :

  • Tâche active ? (is_active: true)
  • Tâche en pause ? (is_paused: false)
  • Expression cron valide ?
  • Crédits suffisants ?

Taux d’échec élevé

Causes possibles :

  • Site cible qui bloque les requêtes
  • URL invalides dans task_payload
  • Délais trop courts
  • Problèmes réseau

Pistes :

  • Délais avec wait_for
  • Autres moteurs (Playwright pour le dynamique)
  • Augmenter les timeouts
  • Consulter l’historique pour les messages d’erreur

Crédits qui fondent trop vite

Pistes :

  • Réduire la fréquence
  • max_executions_per_day
  • Payloads moins coûteux (moins de pages/résultats, formats légers)
  • Historique pour identifier les exécutions coûteuses

Documentation associée

  • Webhooks — Notifications d’événements pour les tâches planifiées
  • API Scrape — Configuration des tâches de scraping
  • API Crawl — Configuration des tâches de crawl

Table des matières

IntroductionFonctionnalités principalesPoints de terminaison de l’APIDémarrage rapideCréer une tâche de scraping quotidienneRéponseGuide des expressions cronExemples courantsParamètres de requêteConfiguration de la tâcheContrôle de concurrenceMétadonnées d’exécution (lecture seule)Intégration webhooksMétadonnéesCharge utile de tâche (task_payload)Tâche scrapeTâche crawlTâche searchTâche templateModes de concurrenceskip (recommandé)queueGestion des tâchesLister toutes les tâchesRéponseMettre une tâche en pauseRéponseReprendre une tâcheMettre à jour une tâcheRéponseSupprimer une tâcheHistorique d’exécutionObtenir les exécutionsRéponseAnnuler une exécutionRéponseGestion automatique des échecsPause automatique après échecs consécutifsSuivi des échecsIntégration avec les webhooksCas d’usage courantsSurveillance de prixSauvegarde hebdomadaire de documentationAgrégation d’actualités quotidienneVeille concurrentielleBonnes pratiques1. Intervalles cron adaptés2. Mode de concurrence3. Crédits4. Santé des tâches5. Noms et étiquettesLimitesDépannageLa tâche ne s’exécute pasTaux d’échec élevéCrédits qui fondent trop viteDocumentation associée