Tác vụ theo lịch

Tự động hóa scrape, crawl và tìm kiếm định kỳ bằng lịch cron.

Giới thiệu

Tác vụ theo lịch cho phép bạn tự động hóa scrape, crawl và thu thập dữ liệu định kỳ bằng biểu thức cron chuẩn. Phù hợp giám sát website, theo dõi giá, lưu trữ nội dung, gom kết quả tìm kiếm hoặc mọi nhu cầu thu thập dữ liệu định kỳ.

Điểm chính: Lịch theo cron có hỗ trợ múi giờ, nhiều chế độ đồng thời, xử lý lỗi tự động, quản lý credit và tích hợp webhook để nhận sự kiện.

Tính năng cốt lõi

Lịch biểu thức cron: Dùng cú pháp cron chuẩn để định nghĩa lịch chạy
Múi giờ: Chạy tác vụ theo bất kỳ múi giờ nào (ví dụ Asia/Shanghai, America/New_York)
Điều khiển đồng thời: Hai chế độ — bỏ qua hoặc xếp hàng khi có lần chạy chồng lấn
Tạm dừng tự động: Tự tạm dừng sau nhiều lỗi liên tiếp để bảo vệ tài nguyên
Quản lý credit: Giới hạn số lần chạy mỗi ngày và ước tính credit
Lịch sử thực thi: Theo dõi mọi lần chạy với trạng thái và chỉ số chi tiết
Tích hợp webhook: Nhận thông báo thời gian thực cho sự kiện tác vụ

Endpoint API

POST   /v1/scheduled-tasks              # Tạo tác vụ theo lịch
GET    /v1/scheduled-tasks              # Liệt kê tất cả tác vụ
GET    /v1/scheduled-tasks/:taskId      # Chi tiết tác vụ
PUT    /v1/scheduled-tasks/:taskId      # Cập nhật tác vụ
PATCH  /v1/scheduled-tasks/:taskId/pause   # Tạm dừng tác vụ
PATCH  /v1/scheduled-tasks/:taskId/resume  # Tiếp tục tác vụ
DELETE /v1/scheduled-tasks/:taskId      # Xóa tác vụ
GET    /v1/scheduled-tasks/:taskId/executions  # Lịch sử thực thi
DELETE /v1/scheduled-tasks/:taskId/executions/:executionId  # Hủy một lần thực thi

Bắt đầu nhanh

Tạo tác vụ scrape hàng ngày

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

Phản hồi

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

Hướng dẫn biểu thức cron

Biểu thức cron dùng 5 trường để định nghĩa lịch:

* * * * *
│ │ │ │ │
│ │ │ │ └─ Ngày trong tuần (0-7, 0 và 7 = Chủ nhật)
│ │ │ └─── Tháng (1-12)
│ │ └───── Ngày trong tháng (1-31)
│ └─────── Giờ (0-23)
└───────── Phút (0-59)

Ví dụ thường gặp

Biểu thức	Mô tả	Thời điểm chạy
`0 9 * * *`	Mỗi ngày lúc 9:00	09:00:00 hàng ngày
`/15 * * *`	Mỗi 15 phút	:00, :15, :30, :45
`0 /6 * *`	Mỗi 6 giờ	00:00, 06:00, 12:00, 18:00
`0 9 * * 1`	Mỗi thứ Hai lúc 9:00	Thứ Hai 09:00:00
`0 0 1 * *`	Ngày đầu tháng	Ngày 1, 00:00:00
`30 2 * * 0`	Mỗi Chủ nhật lúc 2:30	Chủ nhật 02:30:00

Dùng crontab.guru để kiểm tra và hiểu biểu thức cron.

Tham số request

Cấu hình tác vụ

Tham số	Kiểu	Bắt buộc	Mặc định	Mô tả
`name`	string	Có	-	Tên tác vụ (1-255 ký tự)
`description`	string	Không	-	Mô tả tác vụ
`cron_expression`	string	Có	-	Biểu thức cron chuẩn (5 trường)
`timezone`	string	Không	`"UTC"`	Múi giờ thực thi (ví dụ `"Asia/Shanghai"`)
`task_type`	string	Có	-	Loại: `"scrape"`, `"crawl"`, `"search"` hoặc `"template"`
`task_payload`	object	Có	-	Cấu hình tác vụ (xem bên dưới)

Điều khiển đồng thời

Tham số	Kiểu	Bắt buộc	Mặc định	Mô tả
`concurrency_mode`	string	Không	`"skip"`	Chế độ: `"skip"` hoặc `"queue"`
`max_executions_per_day`	number	Không	-	Giới hạn số lần chạy mỗi ngày

Metadata thực thi (chỉ đọc)

Các trường này có trong phản hồi tác vụ và không được gửi trong body tạo/cập nhật:

min_credits_required: Credit tối thiểu ước tính cho một lần chạy (máy chủ tính)
consecutive_failures: Số lỗi liên tiếp dùng để tạm dừng tự động

Tích hợp webhook

Tham số	Kiểu	Bắt buộc	Mặc định	Mô tả
`webhook_ids`	string[]	Không	-	Mảng UUID đăng ký webhook cần kích hoạt
`webhook_url`	string	Không	-	URL webhook trực tiếp (tạo đăng ký ngầm)

Bạn có thể dùng webhook_ids để tham chiếu đăng ký có sẵn, hoặc cung cấp webhook_url để tạo đăng ký ngầm cho tác vụ này.

Metadata

Tham số	Kiểu	Bắt buộc	Mặc định	Mô tả
`tags`	string[]	Không	-	Thẻ để tổ chức
`metadata`	object	Không	-	Metadata tùy chỉnh

Task payload

Tác vụ scrape

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

Tác vụ crawl

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

Tác vụ search

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

Tác vụ template

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

Với task_type: "template", task_payload phải có:

template_id (bắt buộc): template cần chạy
các trường đầu vào theo endpoint mà loại template đó yêu cầu (ví dụ url cho template scrape/crawl, query cho template search)
variables tùy chọn để truyền input động cho template

Chế độ đồng thời

skip (khuyến nghị)

Nếu lần chạy trước vẫn đang chạy, bỏ qua lần hiện tại.

Phù hợp: Tác vụ có thể chạy lâu hơn khoảng cách giữa các lần.

Ví dụ: Job crawl mỗi giờ nhưng đôi khi mất 90 phút.

queue

Xếp lần chạy mới vào hàng đợi sau khi lần trước hoàn tất.

Phù hợp: Mọi lần chạy đều không được bỏ sót.

Ví dụ: Thu thập dữ liệu quan trọng không được miss lịch.

Quản lý tác vụ

Liệt kê tất cả tác vụ

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

Phản hồi

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

Tạm dừng tác vụ

Tạm dừng tác vụ để ngừng chạy tạm thời. Tham số reason được lưu thành pause_reason trong bản ghi.

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

Phản hồi

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

Tiếp tục tác vụ

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

Cập nhật tác vụ

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

Phản hồi

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

Chỉ gửi các trường cần cập nhật. Các trường khác giữ nguyên.

Xóa tác vụ

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

Xóa tác vụ cũng xóa toàn bộ lịch sử thực thi của tác vụ đó.

Lịch sử thực thi

Lấy danh sách thực thi

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

Phản hồi

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

Ghi chú: Các trường credits_used, items_processed, items_succeeded, items_failed, job_status, job_success lấy từ bản ghi job liên quan qua JOIN. duration_ms tính từ started_at và completed_at.

Hủy một lần thực thi

Hủy một lần thực thi đang pending hoặc running. Hữu ích khi cần dừng một lần cụ thể mà không tạm dừng cả tác vụ.

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

Phản hồi

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

Chỉ lần thực thi có trạng thái pending hoặc running mới hủy được. Đã hoàn thành, thất bại hoặc đã hủy sẽ trả lỗi.

Xử lý lỗi tự động

Tạm dừng khi lỗi liên tiếp

Tác vụ tự tạm dừng sau 5 lỗi liên tiếp để tránh lãng phí tài nguyên và gọi API quá mức.

Tiếp tục: Sau khi xử lý nguyên nhân, tiếp tục tác vụ thủ công.

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

Theo dõi lỗi

Theo dõi qua trường consecutive_failures trong trạng thái tác vụ:

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

Theo dõi consecutive_failures. Giá trị cao cho thấy lỗi lặp cần xử lý.

Tích hợp webhook

Đăng ký sự kiện tác vụ qua 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"
  }'

Xem Webhooks để biết thêm.

Tình huống dùng phổ biến

Theo dõi giá

Theo dõi giá sản phẩm mỗi giờ:

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

Sao lưu tài liệu hàng tuần

Crawl và lưu trữ tài liệu mỗi tuần:

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

Gom tin tức hàng ngày

Scrape nhiều nguồn tin mỗi ngày:

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

Tình báo cạnh tranh

Theo dõi đối thủ và xu hướng ngành mỗi giờ:

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

Thực hành tốt

1. Chọn khoảng cron phù hợp

Tránh lịch quá dày (dưới 1 phút) để giảm rate limit
Cân nhắc tần suất cập nhật site khi đặt khoảng cách
Dùng múi giờ cho thời điểm theo vị trí

2. Đặt đúng chế độ đồng thời

Dùng "skip" cho hầu hết tác vụ để tránh chồng lần chạy
Dùng "queue" chỉ khi mọi lần chạy đều bắt buộc

3. Quản lý credit hợp lý

Đặt max_executions_per_day cho tác vụ tốn kém
Xem min_credits_required trong chi tiết tác vụ (ước tính từ máy chủ)
Theo dõi credit trong lịch sử thực thi

4. Giám sát sức khỏe tác vụ

Kiểm tra consecutive_failures định kỳ
Xem lịch sử thực thi để nhận pattern
Cấu hình webhook khi thất bại

5. Tên và thẻ rõ ràng

Đặt tên mô tả, dễ hiểu
Thêm thẻ để lọc và tổ chức
Gắn metadata liên quan để theo dõi

Giới hạn

Mục	Giới hạn
Độ dài tên tác vụ	1-255 ký tự
Khoảng tối thiểu	1 phút
Chế độ đồng thời	`skip`, `queue`
Kích thước task payload	100KB
Định dạng cron	Chuẩn 5 trường

Xử lý sự cố

Tác vụ không chạy

Kiểm tra:

Tác vụ có đang bật? (is_active: true)
Có đang tạm dừng? (is_paused: false)
Biểu thức cron có hợp lệ?
Credit có đủ?

Tỷ lệ lỗi cao

Nguyên nhân có thể:

Site đích chặn request
URL không hợp lệ trong payload
Timeout quá thấp
Lỗi mạng

Cách xử lý:

Tăng độ trễ bằng wait_for
Thử engine khác (Playwright cho site động)
Tăng timeout
Xem lịch sử thực thi để đọc thông báo lỗi

Credit hết quá nhanh

Cách xử lý:

Giảm tần suất chạy
Đặt max_executions_per_day
Dùng payload ít tốn kém hơn (ít trang/kết quả, định dạng nhẹ)
Rà lịch sử để tìm lần chạy tốn kém

Tài liệu liên quan

Webhooks — Thông báo sự kiện cho tác vụ theo lịch
Scrape API — Cấu hình tác vụ scrape
Crawl API — Cấu hình tác vụ crawl

Mục lục