スケジュールタスク

cron ベースのスケジュールで、定期的なスクレイプ・クロール・検索を自動化します。

はじめに

スケジュールタスクでは、標準的な cron 式を使って、定期的な Web スクレイプ、クロール、データ収集を自動化できます。サイトの監視、価格変動の追跡、アーカイブ、検索結果の集約、あらゆる周期データ収集に適しています。

主な特徴: cron スケジュールとタイムゾーン、複数の同時実行モード、自動失敗処理、クレジット管理、イベント通知用の Webhook 連携。

主な機能

Cron 式: 標準 cron 構文で実行スケジュールを定義
タイムゾーン: 任意のタイムゾーンで実行（例: Asia/Shanghai、America/New_York）
同時実行制御: skip または queue の 2 モード
自動一時停止: 連続失敗後に自動停止しリソースを保護
クレジット管理: 1 日あたりの実行上限と推定クレジット
実行履歴: すべての実行とステータス・指標を記録
Webhook: タスクイベントのリアルタイム通知

API エンドポイント

POST   /v1/scheduled-tasks              # タスク作成
GET    /v1/scheduled-tasks              # 一覧
GET    /v1/scheduled-tasks/:taskId      # 詳細
PUT    /v1/scheduled-tasks/:taskId      # 更新
PATCH  /v1/scheduled-tasks/:taskId/pause   # 一時停止
PATCH  /v1/scheduled-tasks/:taskId/resume  # 再開
DELETE /v1/scheduled-tasks/:taskId      # 削除
GET    /v1/scheduled-tasks/:taskId/executions  # 実行履歴
DELETE /v1/scheduled-tasks/:taskId/executions/:executionId  # 実行キャンセル

クイックスタート

毎日のスクレイプタスクを作成

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

レスポンス

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

Cron 式ガイド

Cron 式は 5 フィールドでスケジュールを定義します。

* * * * *
│ │ │ │ │
│ │ │ │ └─ 曜日 (0–7、0 と 7 は日曜)
│ │ │ └─── 月 (1–12)
│ │ └───── 日 (1–31)
│ └─────── 時 (0–23)
└───────── 分 (0–59)

よく使う例

式	説明	実行タイミング
`0 9 * * *`	毎日 9:00	毎日 09:00:00
`/15 * * *`	15 分ごと	:00, :15, :30, :45
`0 /6 * *`	6 時間ごと	00:00, 06:00, 12:00, 18:00
`0 9 * * 1`	毎週月曜 9:00	月曜 09:00:00
`0 0 1 * *`	毎月 1 日	1 日 00:00:00
`30 2 * * 0`	毎週日曜 2:30	日曜 02:30:00

crontab.guru で cron 式の検証と意味の確認ができます。

リクエストパラメータ

タスク設定

パラメータ	型	必須	既定値	説明
`name`	string	はい	-	タスク名（1〜255 文字）
`description`	string	いいえ	-	説明
`cron_expression`	string	はい	-	標準 cron 式（5 フィールド）
`timezone`	string	いいえ	`"UTC"`	実行タイムゾーン（例: `"Asia/Shanghai"`）
`task_type`	string	はい	-	`"scrape"`、`"crawl"`、`"search"`、`"template"` のいずれか
`task_payload`	object	はい	-	タスク本体（下記）

同時実行制御

パラメータ	型	必須	既定値	説明
`concurrency_mode`	string	いいえ	`"skip"`	`"skip"` または `"queue"`
`max_executions_per_day`	number	いいえ	-	1 日あたりの実行上限

実行メタデータ（読み取り専用）

次のフィールドはレスポンスに含まれますが、作成・更新のリクエストボディには含めません。

min_credits_required: 1 回の実行に必要な推定最小クレジット（サーバー計算）
consecutive_failures: 自動一時停止に使う連続失敗回数

Webhook 連携

パラメータ	型	必須	既定値	説明
`webhook_ids`	string[]	いいえ	-	トリガーする Webhook 購読 UUID の配列
`webhook_url`	string	いいえ	-	直接 URL（暗黙の購読を作成）

既存の Webhook は webhook_ids で参照するか、このタスク用に webhook_url で暗黙的な購読を作成できます。

メタデータ

パラメータ	型	必須	既定値	説明
`tags`	string[]	いいえ	-	整理用タグ
`metadata`	object	いいえ	-	任意のメタデータ

タスクペイロード

スクレイプ

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

クロール

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

テンプレート

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

task_type: "template" の場合、task_payload には次が必要です。

template_id（必須）: 実行するテンプレート
そのテンプレート種別が要求する入力（例: スクレイプ／クロールなら url、検索なら query）
任意の variables で動的入力を渡す

同時実行モード

skip（推奨）

前回の実行がまだ終わっていれば、今回の実行をスキップします。

向いている: 実行時間が間隔より長くなることがあるタスク。

例: 1 時間ごとのクロールで、たまに 90 分かかる場合。

queue

前の実行が終わるまで新しい実行をキューに入れます。

向いている: どの実行もスキップできないタスク。

例: スケジュールどおりの実行が欠かせない重要なデータ収集。

タスクの管理

一覧

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

レスポンス

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

一時停止

タスクを一時停止します。reason は 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"
  }'

レスポンス

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

再開

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

更新

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

レスポンス

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

変更したいフィールドだけ送ってください。それ以外はそのままです。

削除

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

タスクを削除すると、実行履歴もすべて削除されます。

実行履歴

取得

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

レスポンス

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

注: credits_used、items_processed、items_succeeded、items_failed、job_status、job_success は関連ジョブを JOIN して取得しています。duration_ms は started_at と completed_at から算出されます。

実行のキャンセル

pending または running の実行を 1 件キャンセルします。タスク全体を止めずに特定の実行だけ止めたいときに使います。

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

レスポンス

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

キャンセルできるのは pending または running のみです。完了・失敗・既にキャンセル済みはエラーになります。

自動失敗処理

連続失敗で自動一時停止

連続 5 回失敗すると自動で一時停止し、無駄な API 呼び出しを防ぎます。

再開: 原因を直したうえで手動で resume してください。

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

失敗の監視

consecutive_failures で状況を追います。

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

consecutive_failures が高いと、繰り返し問題があるサインです。

Webhook との連携

タスクイベントを Webhook で受け取れます。

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

詳しくは Webhooks を参照してください。

よくある使い方

価格監視

1 時間ごとに商品ページを監視:

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

週次ドキュメントバックアップ

週に一度ドキュメントをクロールしてアーカイブ:

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

毎朝のニュース

毎日決まった時刻にニュースをスクレイプ:

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

競合・インテリジェンス

検索で競合名や業界トレンドを毎時追跡:

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

ベストプラクティス

1. Cron の間隔を適切に

1 分未満のような短すぎる間隔はレート制限の原因になりやすい
サイトの更新頻度に合わせる
地域に合わせてタイムゾーンを設定する

2. 同時実行モード

多くの場合は重複を避けるため "skip"
すべての実行が必須なら "queue"

3. クレジット

コストの高いタスクには max_executions_per_day
タスク詳細の min_credits_required（サーバー推定）を確認
実行履歴で消費を追う

4. 健全性

consecutive_failures を定期的に確認
実行履歴でパターンを見る
失敗時は Webhook で通知

5. 名前とタグ

わかりやすいタスク名
フィルタ用のタグ
追跡用の metadata

制限

項目	制限
タスク名の長さ	1〜255 文字
最短間隔	1 分
同時実行モード	`skip`、`queue`
ペイロードサイズ	100KB
Cron 形式	標準 5 フィールド

トラブルシューティング

実行されない

確認:

is_active: true か
is_paused: false か
cron 式は有効か
クレジットは十分か

失敗が多い

想定される原因:

対象サイトがブロックしている
ペイロードの URL が無効
タイムアウトが短い
ネットワークの問題

対処:

wait_for で待機を増やす
動的サイトは Playwright など別エンジンを試す
タイムアウトを延ばす
実行履歴のエラーメッセージを確認

クレジットが消費しすぎ

対処:

実行頻度を下げる
max_executions_per_day を設定
ページ数・結果数・軽い形式などに軽量化
履歴で高コストの実行を特定

スケジュールタスク

目次