AnyCrawl

Tareas programadas

Automatiza scraping, rastreo y búsquedas recurrentes con programación tipo cron.

Introducción

Las tareas programadas permiten automatizar operaciones recurrentes de scraping, rastreo y recopilación de datos con expresiones cron estándar. Son ideales para monitorizar sitios, seguir cambios de precios, archivar contenido, agregar resultados de búsqueda o cualquier recopilación periódica.

Características clave: programación con cron y zona horaria, varios modos de concurrencia, manejo automático de fallos, gestión de créditos e integración con webhooks para notificaciones.

Funciones principales

  • Programación con expresiones cron: sintaxis cron estándar para definir horarios
  • Zona horaria: ejecuta tareas en cualquier zona (p. ej. Asia/Shanghai, America/New_York)
  • Control de concurrencia: dos modos: omitir o encolar ejecuciones simultáneas
  • Pausa automática: se pausa tras fallos consecutivos para proteger recursos
  • Gestión de créditos: límites diarios de ejecución y estimación de créditos
  • Historial de ejecuciones: seguimiento con estado y métricas
  • Integración con webhooks: notificaciones en tiempo real de eventos de la tarea

Endpoints de la API

POST   /v1/scheduled-tasks              # Create a scheduled task
GET    /v1/scheduled-tasks              # List all tasks
GET    /v1/scheduled-tasks/:taskId      # Get task details
PUT    /v1/scheduled-tasks/:taskId      # Update task
PATCH  /v1/scheduled-tasks/:taskId/pause   # Pause task
PATCH  /v1/scheduled-tasks/:taskId/resume  # Resume task
DELETE /v1/scheduled-tasks/:taskId      # Delete task
GET    /v1/scheduled-tasks/:taskId/executions  # Get execution history
DELETE /v1/scheduled-tasks/:taskId/executions/:executionId  # Cancel an execution

Inicio rápido

Crear una tarea de scraping diaria

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
  }'

Respuesta

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

Guía de expresiones cron

Las expresiones cron usan 5 campos para definir el horario:

* * * * *
│ │ │ │ │
│ │ │ │ └─ Day of week (0-7, 0 and 7 = Sunday)
│ │ │ └─── Month (1-12)
│ │ └───── Day of month (1-31)
│ └─────── Hour (0-23)
└───────── Minute (0-59)

Ejemplos habituales

ExpressionDescripciónHora de ejecución
0 9 * * *Todos los días a las 9:0009:00:00 cada día
*/15 * * * *Cada 15 minutos:00, :15, :30, :45
0 */6 * * *Cada 6 horas00:00, 06:00, 12:00, 18:00
0 9 * * 1Cada lunes a las 9:00Lunes 09:00:00
0 0 1 * *Primer día del mesDía 1, 00:00:00
30 2 * * 0Cada domingo a las 2:30Domingo 02:30:00

Usa crontab.guru para validar y entender expresiones cron.

Parámetros de la solicitud

Configuración de la tarea

ParameterTypeRequiredDefaultDescription
namestringYes-Nombre de la tarea (1-255 caracteres)
descriptionstringNo-Descripción de la tarea
cron_expressionstringYes-Expresión cron estándar (5 campos)
timezonestringNo"UTC"Zona horaria de ejecución (p. ej. "Asia/Shanghai")
task_typestringYes-Tipo: "scrape", "crawl", "search" o "template"
task_payloadobjectYes-Configuración de la tarea (ver abajo)

Control de concurrencia

ParameterTypeRequiredDefaultDescription
concurrency_modestringNo"skip"Modo: "skip" u "queue"
max_executions_per_daynumberNo-Límite de ejecuciones diarias

Metadatos de ejecución (solo lectura)

Estos campos se devuelven en las respuestas de la tarea y no se aceptan en el cuerpo de creación o actualización:

  • min_credits_required: créditos mínimos estimados por ejecución (calculado en el servidor)
  • consecutive_failures: contador de fallos consecutivos usado para la pausa automática

Integración con webhooks

ParameterTypeRequiredDefaultDescription
webhook_idsstring[]No-UUIDs de suscripciones webhook a disparar
webhook_urlstringNo-URL directa de webhook (crea una suscripción implícita)

Puedes usar webhook_ids para referenciar suscripciones existentes, o indicar webhook_url para crear una suscripción implícita para esta tarea.

Metadatos

ParameterTypeRequiredDefaultDescription
tagsstring[]No-Etiquetas para organizar
metadataobjectNo-Metadatos personalizados

Cuerpo de la tarea (task payload)

Tarea de tipo scrape

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

Tarea de tipo 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"
}

Tarea de tipo template

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

Para task_type: "template", task_payload debe incluir:

  • template_id (obligatorio): plantilla a ejecutar
  • campos de entrada propios del tipo de plantilla (p. ej. url para plantillas scrape/crawl, query para búsqueda)
  • variables opcional para entradas dinámicas de la plantilla

Modos de concurrencia

skip (recomendado)

Si una ejecución anterior sigue en curso, se omite la actual.

Ideal para: tareas que pueden durar más que el intervalo entre ejecuciones.

Ejemplo: un crawl cada hora que a veces tarda 90 minutos.

queue

Encola la nueva ejecución y espera a que termine la anterior.

Ideal para: tareas en las que no puede omitirse ninguna ejecución.

Ejemplo: recopilación crítica que no puede perder ningún ciclo programado.

Gestión de tareas

Listar todas las tareas

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

Respuesta

{
  "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"
    }
  ]
}

Pausar una tarea

Pausa una tarea para detener temporalmente su ejecución. El parámetro reason se guarda como pause_reason en el registro.

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"
  }'

Respuesta

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

Reanudar una tarea

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

Actualizar una tarea

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"
  }'

Respuesta

{
  "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"
  }
}

Incluye solo los campos que quieras cambiar. El resto permanece igual.

Eliminar una tarea

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

Al eliminar una tarea también se borra todo su historial de ejecuciones.

Historial de ejecuciones

Obtener ejecuciones

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

Respuesta

{
  "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"
    }
  ]
}

Nota: Los campos credits_used, items_processed, items_succeeded, items_failed, job_status y job_success provienen del trabajo asociado (JOIN). duration_ms se calcula con started_at y completed_at.

Cancelar una ejecución

Cancela una ejecución concreta pendiente o en curso. Útil para detener una ejecución sin pausar toda la tarea.

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

Respuesta

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

Solo se pueden cancelar ejecuciones en estado pending o running. Las completadas, fallidas o ya canceladas devuelven error.

Manejo automático de fallos

Pausa automática por fallos consecutivos

Las tareas se pausan automáticamente tras 5 fallos consecutivos para evitar desperdicio de recursos y llamadas excesivas a la API.

Reanudación: reanuda manualmente la tarea tras corregir la causa.

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

Supervisar fallos

Usa el campo consecutive_failures en el estado de la tarea:

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

Supervisa consecutive_failures. Valores altos indican problemas recurrentes.

Integración con webhooks

Suscríbete a eventos de tarea con 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"
  }'

Consulta Webhooks para más detalles.

Casos de uso habituales

Monitorización de precios

Monitoriza precios de producto cada hora:

{
  "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"
}

Copia de seguridad semanal de documentación

Rastrea y archiva documentación cada semana:

{
  "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
}

Agregación diaria de noticias

Scrape de fuentes de noticias cada día:

{
  "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
}

Inteligencia competitiva

Sigue menciones de competidores y tendencias del sector cada hora:

{
  "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"
}

Buenas prácticas

1. Intervalos cron adecuados

  • Evita frecuencias excesivas (< 1 minuto) para no chocar con límites de tasa
  • Ajusta el intervalo a la frecuencia real de actualización del sitio
  • Usa zona horaria cuando el momento del día importe por ubicación

2. Modo de concurrencia

  • Usa "skip" en la mayoría de los casos para no solapar ejecuciones
  • Usa "queue" solo cuando cada ejecución sea crítica

3. Gestión de créditos

  • Define max_executions_per_day en tareas costosas
  • Revisa min_credits_required en el detalle (estimación del servidor)
  • Supervisa el uso de créditos en el historial

4. Salud de la tarea

  • Revisa consecutive_failures con regularidad
  • Analiza el historial en busca de patrones
  • Configura webhooks para fallos

5. Nombres y etiquetas claros

  • Nombres descriptivos
  • Etiquetas para filtrar y organizar
  • Metadatos útiles para seguimiento

Limitaciones

ItemLimit
Longitud del nombre1-255 caracteres
Intervalo mínimo1 minuto
Modos de concurrenciaskip, queue
Tamaño del payload100KB
Formato cron5 campos estándar

Solución de problemas

La tarea no se ejecuta

Comprueba:

  • ¿Está activa? (is_active: true)
  • ¿Está pausada? (is_paused: false)
  • ¿La expresión cron es válida?
  • ¿Hay créditos suficientes?

Muchos fallos

Posibles causas:

  • El sitio bloquea peticiones
  • URLs inválidas en el payload
  • Timeouts insuficientes
  • Problemas de red

Qué hacer:

  • Añade retrasos con wait_for
  • Prueba otros motores (p. ej. Playwright en sitios dinámicos)
  • Aumenta timeouts
  • Revisa el historial para mensajes de error

Los créditos bajan muy rápido

Qué hacer:

  • Reduce la frecuencia
  • Limita con max_executions_per_day
  • Usa payloads más baratos (menos páginas/resultados, formatos ligeros)
  • Revisa el historial para identificar ejecuciones costosas

Documentación relacionada

  • Webhooks — Notificaciones de eventos para tareas programadas
  • API Scrape — Configuración de tareas de scraping
  • API Crawl — Configuración de tareas de rastreo

Tabla de contenidos

IntroducciónFunciones principalesEndpoints de la APIInicio rápidoCrear una tarea de scraping diariaRespuestaGuía de expresiones cronEjemplos habitualesParámetros de la solicitudConfiguración de la tareaControl de concurrenciaMetadatos de ejecución (solo lectura)Integración con webhooksMetadatosCuerpo de la tarea (task payload)Tarea de tipo scrapeTarea de tipo crawlTarea de tipo searchTarea de tipo templateModos de concurrenciaskip (recomendado)queueGestión de tareasListar todas las tareasRespuestaPausar una tareaRespuestaReanudar una tareaActualizar una tareaRespuestaEliminar una tareaHistorial de ejecucionesObtener ejecucionesRespuestaCancelar una ejecuciónRespuestaManejo automático de fallosPausa automática por fallos consecutivosSupervisar fallosIntegración con webhooksCasos de uso habitualesMonitorización de preciosCopia de seguridad semanal de documentaciónAgregación diaria de noticiasInteligencia competitivaBuenas prácticas1. Intervalos cron adecuados2. Modo de concurrencia3. Gestión de créditos4. Salud de la tarea5. Nombres y etiquetas clarosLimitacionesSolución de problemasLa tarea no se ejecutaMuchos fallosLos créditos bajan muy rápidoDocumentación relacionada