AnyCrawl

Tarefas agendadas

Automatize scraping, crawling e buscas recorrentes com agendamento baseado em cron.

Introdução

As tarefas agendadas permitem automatizar scraping, crawling e coleta de dados recorrentes com expressões cron padrão. Ideal para monitorar sites, acompanhar preços, arquivar conteúdo, agregar resultados de busca ou qualquer coleta periódica.

Destaques: agendamento com cron e fuso horário, modos de concorrência, tratamento automático de falhas, gestão de créditos e integração com webhooks para notificações.

Recursos principais

  • Agendamento com cron: sintaxe cron padrão para definir execuções
  • Fuso horário: execute em qualquer timezone (ex.: Asia/Shanghai, America/New_York)
  • Concorrência: dois modos — pular ou enfileirar execuções simultâneas
  • Pausa automática: pausa após falhas consecutivas para proteger recursos
  • Créditos: limite diário de execuções e estimativa de créditos
  • Histórico de execuções: acompanhe todas com status e métricas
  • Webhooks: notificações em tempo real para eventos da tarefa

Endpoints da API

POST   /v1/scheduled-tasks              # Criar tarefa agendada
GET    /v1/scheduled-tasks              # Listar tarefas
GET    /v1/scheduled-tasks/:taskId      # Detalhes da tarefa
PUT    /v1/scheduled-tasks/:taskId      # Atualizar tarefa
PATCH  /v1/scheduled-tasks/:taskId/pause   # Pausar tarefa
PATCH  /v1/scheduled-tasks/:taskId/resume  # Retomar tarefa
DELETE /v1/scheduled-tasks/:taskId      # Excluir tarefa
GET    /v1/scheduled-tasks/:taskId/executions  # Histórico de execuções
DELETE /v1/scheduled-tasks/:taskId/executions/:executionId  # Cancelar execução

Início rápido

Criar uma tarefa diária de scraping

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

Resposta

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

Guia de expressões cron

Expressões cron usam 5 campos para definir o agendamento:

* * * * *
│ │ │ │ │
│ │ │ │ └─ Dia da semana (0-7, 0 e 7 = domingo)
│ │ │ └─── Mês (1-12)
│ │ └───── Dia do mês (1-31)
│ └─────── Hora (0-23)
└───────── Minuto (0-59)

Exemplos comuns

ExpressãoDescriçãoHorário de execução
0 9 * * *Todo dia às 9:0009:00:00 diariamente
*/15 * * * *A cada 15 minutos:00, :15, :30, :45
0 */6 * * *A cada 6 horas00:00, 06:00, 12:00, 18:00
0 9 * * 1Toda segunda às 9hSegunda 09:00:00
0 0 1 * *Primeiro dia do mêsDia 1, 00:00:00
30 2 * * 0Todo domingo às 2:30Domingo 02:30:00

Use crontab.guru para validar e entender expressões cron.

Parâmetros da requisição

Configuração da tarefa

ParâmetroTipoObrigatórioPadrãoDescrição
namestringSim-Nome da tarefa (1–255 caracteres)
descriptionstringNão-Descrição da tarefa
cron_expressionstringSim-Expressão cron padrão (5 campos)
timezonestringNão"UTC"Fuso para execução (ex.: "Asia/Shanghai")
task_typestringSim-Tipo: "scrape", "crawl", "search" ou "template"
task_payloadobjectSim-Configuração da tarefa (veja abaixo)

Controle de concorrência

ParâmetroTipoObrigatórioPadrãoDescrição
concurrency_modestringNão"skip"Modo: "skip" ou "queue"
max_executions_per_daynumberNão-Limite diário de execuções

Metadados de execução (somente leitura)

Esses campos aparecem nas respostas da tarefa e não são aceitos em criar/atualizar:

  • min_credits_required: créditos mínimos estimados por execução (calculado pelo servidor)
  • consecutive_failures: contagem de falhas consecutivas para pausa automática

Integração com webhooks

ParâmetroTipoObrigatórioPadrãoDescrição
webhook_idsstring[]Não-UUIDs de assinaturas de webhook a disparar
webhook_urlstringNão-URL de webhook direta (cria assinatura implícita)

Use webhook_ids para referenciar assinaturas existentes ou informe webhook_url para criar uma assinatura implícita para esta tarefa.

Metadados

ParâmetroTipoObrigatórioPadrãoDescrição
tagsstring[]Não-Tags para organização
metadataobjectNão-Metadados personalizados

Payload da tarefa

Tarefa de scrape

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

Tarefa de crawl

{
  "url": "https://example.com",
  "engine": "playwright",
  "options": {
    "max_depth": 3,
    "limit": 50,
    "strategy": "same-domain",
    "exclude_paths": ["/admin/*", "/api/*"],
    "scrape_options": {
      "formats": ["markdown"]
    }
  }
}

Tarefa de busca

{
  "query": "artificial intelligence news",
  "engine": "google",
  "limit": 20,
  "country": "US",
  "lang": "en",
  "timeRange": "day"
}

Tarefa de template

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

Para task_type: "template", task_payload deve incluir:

  • template_id (obrigatório): template a executar
  • campos exigidos pelo tipo de template (por exemplo url em scrape/crawl, query em search)
  • variables opcionais para entradas dinâmicas do template

Modos de concorrência

skip (recomendado)

Se a execução anterior ainda estiver em andamento, pule a atual.

Ideal para: tarefas que podem durar mais que o intervalo entre execuções.

Exemplo: crawl a cada hora que às vezes leva 90 minutos.

queue

Enfileira a nova execução e aguarda a anterior terminar.

Ideal para: quando toda execução precisa ocorrer sem ser pulada.

Exemplo: coleta crítica que não pode perder agendamentos.

Gerenciar tarefas

Listar todas as tarefas

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

Resposta

{
  "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 uma tarefa

Pausa a tarefa para interromper temporariamente execuções. O parâmetro reason é salvo como pause_reason no 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"
  }'

Resposta

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

Retomar uma tarefa

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

Atualizar uma tarefa

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

Resposta

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

Inclua apenas os campos que deseja alterar. Os demais permanecem iguais.

Excluir uma tarefa

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

Excluir a tarefa também remove todo o histórico de execuções.

Histórico de execuções

Obter execuções

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

Resposta

{
  "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: os campos credits_used, items_processed, items_succeeded, items_failed, job_status e job_success vêm do job associado (JOIN). duration_ms é calculado a partir de started_at e completed_at.

Cancelar uma execução

Cancela uma execução pendente ou em andamento. Útil para parar uma execução específica sem pausar a tarefa inteira.

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

Resposta

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

Somente execuções com status pending ou running podem ser canceladas. Concluídas, com falha ou já canceladas retornam erro.

Tratamento automático de falhas

Pausa automática por falhas consecutivas

As tarefas são pausadas automaticamente após 5 falhas consecutivas para evitar desperdício de recursos e chamadas excessivas à API.

Retomar: retome manualmente após corrigir a causa.

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

Monitorar falhas

Acompanhe falhas pelo campo consecutive_failures no status da tarefa:

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

Monitore consecutive_failures. Valores altos indicam problemas recorrentes.

Integração com webhooks

Inscreva-se em eventos da tarefa com 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"
  }'

Veja Webhooks para mais detalhes.

Casos de uso comuns

Monitoramento de preço

Monitore preços de produtos a 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"
}

Backup semanal de documentação

Faça crawl e arquive a documentação semanalmente:

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

Agregação diária de notícias

Faça scrape de fontes de notícias diariamente:

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

Inteligência competitiva

Acompanhe menções a concorrentes e tendências do setor a 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"
}

Boas práticas

1. Escolha intervalos cron adequados

  • Evite agendamentos muito frequentes (< 1 minuto) para não bater em limites de taxa
  • Considere a frequência de atualização do site ao definir o intervalo
  • Use fuso horário para horários específicos de região

2. Defina o modo de concorrência corretamente

  • Use "skip" na maioria das tarefas para evitar sobreposição
  • Use "queue" só quando cada execução for crítica

3. Gerencie créditos com critério

  • Defina max_executions_per_day para tarefas caras
  • Revise min_credits_required nos detalhes (estimativa do servidor)
  • Monitore uso de créditos no histórico

4. Monitore a saúde da tarefa

  • Verifique consecutive_failures com regularidade
  • Analise o histórico em busca de padrões
  • Configure webhooks para falhas

5. Nomes e tags descritivos

  • Use nomes claros para as tarefas
  • Adicione tags para filtrar e organizar
  • Inclua metadados úteis para rastreio

Limitações

ItemLimite
Tamanho do nome da tarefa1–255 caracteres
Intervalo mínimo1 minuto
Modos de concorrênciaskip, queue
Tamanho do payload100KB
Formato cronPadrão de 5 campos

Solução de problemas

Tarefa não executa

Verifique:

  • A tarefa está ativa? (is_active: true)
  • Está pausada? (is_paused: false)
  • A expressão cron é válida?
  • Há créditos suficientes?

Alta taxa de falha

Possíveis causas:

  • Site bloqueando requisições
  • URLs inválidas no payload
  • Timeouts insuficientes
  • Problemas de rede

Soluções:

  • Atrasos com wait_for
  • Outros motores (Playwright para sites dinâmicos)
  • Aumente timeouts
  • Veja mensagens de erro no histórico

Créditos acabando rápido

Soluções:

  • Reduza a frequência
  • Limite com max_executions_per_day
  • Payloads mais baratos (menos páginas/resultados, formatos mais leves)
  • Revise o histórico para identificar execuções caras

Documentação relacionada

  • Webhooks — Notificações de eventos para tarefas agendadas
  • API Scrape — Configuração de tarefas de scraping
  • API Crawl — Configuração de tarefas de crawling

Sumário

IntroduçãoRecursos principaisEndpoints da APIInício rápidoCriar uma tarefa diária de scrapingRespostaGuia de expressões cronExemplos comunsParâmetros da requisiçãoConfiguração da tarefaControle de concorrênciaMetadados de execução (somente leitura)Integração com webhooksMetadadosPayload da tarefaTarefa de scrapeTarefa de crawlTarefa de buscaTarefa de templateModos de concorrênciaskip (recomendado)queueGerenciar tarefasListar todas as tarefasRespostaPausar uma tarefaRespostaRetomar uma tarefaAtualizar uma tarefaRespostaExcluir uma tarefaHistórico de execuçõesObter execuçõesRespostaCancelar uma execuçãoRespostaTratamento automático de falhasPausa automática por falhas consecutivasMonitorar falhasIntegração com webhooksCasos de uso comunsMonitoramento de preçoBackup semanal de documentaçãoAgregação diária de notíciasInteligência competitivaBoas práticas1. Escolha intervalos cron adequados2. Defina o modo de concorrência corretamente3. Gerencie créditos com critério4. Monitore a saúde da tarefa5. Nomes e tags descritivosLimitaçõesSolução de problemasTarefa não executaAlta taxa de falhaCréditos acabando rápidoDocumentação relacionada