Schedules

Schedules allow you to configure recurring task executions using cron expressions. While one-off delayed tasks are handled through the Tasks API, schedules provide a way to create tasks that need to run on a recurring basis.

Understanding task creation

Schedules automatically create tasks based on their cron configuration. Here's how task creation works:

Each schedule creates new tasks at its specified cron interval
Each created task follows its own retry policy
Tasks are typically created 5 minutes before their scheduled execution time
If a previous task has failed and has scheduled retries or is still processing, a new task will not be created
If the server experiences downtime, it will create any missed tasks from the last hour upon restart (configurable)

POST/v1/schedules

Create a schedule

This endpoint creates a new recurring schedule for task creation.

Required attributes

Name
cron
Type
string
Description
Cron expression (e.g. "0 9 * * *" for daily at 9 AM)
Name
timezone
Type
string
Description
Timezone for the cron expression (e.g. "America/New_York")
Name
task_template
Type
object
Description
Template for created tasks

Optional attributes

Name
start_at
Type
string
Description
ISO8601 timestamp (inclusive) when the schedule becomes active
Name
end_at
Type
string
Description
ISO8601 timestamp (inclusive) when the schedule becomes inactive
Name
enabled
Type
boolean
Description
Whether to start the schedule enabled (default: true)

Request

POST

/v1/schedules

curl https://api.taskhook.io/v1/schedules \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "cron": "0 9 * * *",
    "timezone": "America/New_York",
    "start_at": "2024-03-01T00:00:00Z",
    "end_at": "2024-12-31T23:59:59Z",
    "task_template": {
      "target": "https://example.com/scheduled-job",
      "payload": {"key": "value"}
    }
  }'

Response

{
  "id": "schedule_123",
  "status": "active",
  "cron": "0 9 * * *",
  "timezone": "America/New_York",
  "start_at": "2024-03-01T00:00:00Z",
  "end_at": "2024-12-31T23:59:59Z",
  "task_template": {
    "target": "https://example.com/scheduled-job",
    "payload": {
      "key": "value"
    }
  },
  "enabled": true,
  "next_execution_at": "2024-03-01T14:00:00Z",
  "last_execution_at": null,
  "execution_count": 0,
  "created_at": "2024-01-30T12:00:00Z",
  "updated_at": "2024-01-30T12:00:00Z"
}

GET/v1/schedules

List all schedules

Retrieve a paginated list of all recurring schedules. Results are ordered by creation date, with newest first.

Optional attributes

Name
status
Type
string
Description
Filter by status (active, disabled)
Name
enabled
Type
boolean
Description
Filter by enabled/disabled state
Name
limit
Type
integer
Description
Maximum number of schedules to return (default: 100)
Name
offset
Type
integer
Description
Number of schedules to skip (default: 0)

Request

GET

/v1/schedules

curl -G https://api.taskhook.io/v1/schedules \
  -H "Authorization: Bearer {token}" \
  -d status=active \
  -d enabled=true \
  -d limit=10

Response

{
  "total": 2,
  "schedules": [
    {
      "id": "schedule_123",
      "status": "active",
      "cron": "0 9 * * *",
      "timezone": "America/New_York",
      "start_at": "2024-03-01T00:00:00Z",
      "end_at": "2024-12-31T23:59:59Z",
      "task_template": {
        "target": "https://example.com/scheduled-job",
        "payload": {
          "key": "value"
        }
      },
      "enabled": true,
      "next_execution_at": "2024-03-01T14:00:00Z",
      "execution_count": 5,
      "created_at": "2024-01-30T12:00:00Z",
      "updated_at": "2024-01-30T12:00:00Z"
    }
  ]
}

GET/v1/schedules/:id

Retrieve a schedule

Get details of a specific recurring schedule by its ID.

Request

GET

/v1/schedules/schedule_123

curl https://api.taskhook.io/v1/schedules/schedule_123 \
  -H "Authorization: Bearer {token}"

Response

{
  "id": "schedule_123",
  "status": "active",
  "cron": "0 9 * * *",
  "timezone": "America/New_York",
  "start_at": "2024-03-01T00:00:00Z",
  "end_at": "2024-12-31T23:59:59Z",
  "task_template": {
    "target": "https://example.com/scheduled-job",
    "payload": {
      "key": "value"
    }
  },
  "enabled": true,
  "next_execution_at": "2024-03-01T14:00:00Z",
  "last_execution_at": "2024-02-28T14:00:00Z",
  "execution_count": 5,
  "created_at": "2024-01-30T12:00:00Z",
  "updated_at": "2024-01-30T12:00:00Z"
}

PATCH/v1/schedules/:id

Update a schedule

Update a schedule's configuration. Changes affect only future task creation.

Updatable attributes

Name
enabled
Type
boolean
Description
Enable/disable the schedule
Name
cron
Type
string
Description
New cron expression
Name
timezone
Type
string
Description
New timezone
Name
start_at
Type
string
Description
New start time (ISO8601)
Name
end_at
Type
string
Description
New end time (ISO8601)
Name
task_template
Type
object
Description
Update template for future tasks

Request

PATCH

/v1/schedules/schedule_123

curl -X PATCH https://api.taskhook.io/v1/schedules/schedule_123 \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": false,
    "end_at": "2024-06-30T23:59:59Z",
    "cron": "0 */4 * * *"
  }'

Response

{
  "id": "schedule_123",
  "enabled": false,
  "cron": "0 */4 * * *",
  "end_at": "2024-06-30T23:59:59Z"
}

DELETE/v1/schedules/:id

Delete a schedule

Permanently delete a schedule. This will:

Stop creation of new tasks
Not affect already created tasks
Not cancel pending tasks
Mark the schedule as deleted

Request

DELETE

/v1/schedules/schedule_123

curl -X DELETE https://api.taskhook.io/v1/schedules/schedule_123 \
  -H "Authorization: Bearer {token}"

Response

{
  "id": "schedule_123",
  "status": "deleted"
}

GET/v1/schedules/:id/tasks

List schedule's tasks

List all tasks that were created by this schedule. Tasks are returned in reverse chronological order.

Optional attributes

Name
status
Type
string
Description
Filter by task status (queued, processing, completed, failed)
Name
limit
Type
integer
Description
Maximum number of tasks (default: 100)
Name
offset
Type
integer
Description
Number of tasks to skip (default: 0)

Request

GET

/v1/schedules/schedule_123/tasks

curl -G https://api.taskhook.io/v1/schedules/schedule_123/tasks \
  -H "Authorization: Bearer {token}" \
  -d status=completed

Response

{
  "total": 50,
  "tasks": [
    {
      "id": "task_789",
      "schedule_id": "schedule_123",
      "scheduled_for": "2024-03-01T14:00:00Z",
      "status": "completed",
      "target": "https://example.com/scheduled-job",
      "payload": {
        "key": "value"
      },
      "created_at": "2024-03-01T13:55:00Z"
    }
  ]
}

GET/v1/schedules/:id/preview

Preview schedule executions

Preview the next N execution times for a schedule based on its cron expression and timezone.

Optional attributes

Name
limit
Type
integer
Description
Number of executions to preview (default: 10, max: 100)
Name
start_from
Type
string
Description
ISO8601 timestamp to start preview from (default: current time)

Request

GET

/v1/schedules/schedule_123/preview

curl -G https://api.taskhook.io/v1/schedules/schedule_123/preview \
  -H "Authorization: Bearer {token}" \
  -d limit=5 \
  -d start_from="2024-03-01T00:00:00Z"

Response

{
  "schedule_id": "schedule_123",
  "executions": [
    {
      "scheduled_for": "2024-03-01T14:00:00Z",
      "local_time": "2024-03-01T09:00:00-05:00"
    },
    {
      "scheduled_for": "2024-03-02T14:00:00Z",
      "local_time": "2024-03-02T09:00:00-05:00"
    },
    {
      "scheduled_for": "2024-03-03T14:00:00Z",
      "local_time": "2024-03-03T09:00:00-05:00"
    },
    {
      "scheduled_for": "2024-03-04T14:00:00Z",
      "local_time": "2024-03-04T09:00:00-05:00"
    },
    {
      "scheduled_for": "2024-03-05T14:00:00Z",
      "local_time": "2024-03-05T09:00:00-05:00"
    }
  ]
}