Task Lifecycle

This document details the complete lifecycle of a task: enqueuing, listing, reserving, extending leases, acknowledging, rescheduling, and SSE snapshots.

Task States

A task moves through the following states:

pending — Waiting for its scheduled time. Not yet visible to workers.
available — Scheduled time has elapsed; ready for reservation.
reserved — Held by a worker under a lease.
completed — Acknowledged and removed by the worker.

If a lease expires without acknowledgement, the task returns to available.

Enqueuing a Task

Create a new task with an id, payload, future time (or delay), and optional labels:

 1curl -X POST "https://api.hola.cloud/schedulers/sched-a1b2c3d4-e5f6-7890-abcd-ef1234567890/tasks" \
 2  -H "X-API-Key: YOUR_API_KEY" \
 3  -H "Content-Type: application/json" \
 4  -d '{
 5    "id": "task-001",
 6    "payload": {
 7      "action": "generate_report",
 8      "report_id": "rpt-5678"
 9    },
10    "future": "2025-06-22T00:00:00Z",
11    "labels": ["team:analytics", "env:production"]
12  }'

 1POST /schedulers/sched-a1b2c3d4-e5f6-7890-abcd-ef1234567890/tasks HTTP/1.1
 2Host: api.hola.cloud
 3X-API-Key: YOUR_API_KEY
 4Content-Type: application/json
 5
 6{
 7  "id": "task-001",
 8  "payload": {
 9    "action": "generate_report",
10    "report_id": "rpt-5678"
11  },
12  "future": "2025-06-22T00:00:00Z",
13  "labels": ["team:analytics", "env:production"]
14}

Alternatively, use delay as a Go duration string instead of future:

1{
2  "payload": { "action": "send_reminder" },
3  "delay": "1h",
4  "labels": ["type:email"]
5}

Expected response: HTTP 202 Accepted with an empty body.

Listing Tasks with Pagination

List tasks with optional pagination and label filtering:

1curl "https://api.hola.cloud/schedulers/sched-a1b2c3d4-e5f6-7890-abcd-ef1234567890/tasks?scheduled_page=1&scheduled_per_page=20"

1GET /schedulers/sched-a1b2c3d4-e5f6-7890-abcd-ef1234567890/tasks?scheduled_page=1&scheduled_per_page=20 HTTP/1.1
2Host: api.hola.cloud

Expected response:

 1{
 2  "scheduled": [
 3    {
 4      "id": "task-001",
 5      "future": "2025-06-22T00:00:00Z",
 6      "labels": ["team:analytics"]
 7    }
 8  ],
 9  "inflight": [
10    {
11      "id": "task-002",
12      "lease_expires_at": "2025-06-21T12:01:00Z",
13      "labels": ["team:analytics"]
14    }
15  ],
16  "scheduled_meta": { "page": 1, "per_page": 20, "total": 1, "total_pages": 1 },
17  "inflight_meta": { "page": 1, "per_page": 25, "total": 1, "total_pages": 1 }
18}

Reserving a Task

A worker reserves an available task by specifying worktime as a Go duration string:

1curl -X POST "https://api.hola.cloud/schedulers/sched-a1b2c3d4-e5f6-7890-abcd-ef1234567890/tasks/reserve" \
2  -H "X-API-Key: YOUR_API_KEY" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "worktime": "60s"
6  }'

1POST /schedulers/sched-a1b2c3d4-e5f6-7890-abcd-ef1234567890/tasks/reserve HTTP/1.1
2Host: api.hola.cloud
3X-API-Key: YOUR_API_KEY
4Content-Type: application/json
5
6{
7  "worktime": "60s"
8}

Expected response:

1{
2  "id": "task-002",
3  "payload": { "action": "send_reminder" },
4  "lease_expires_at": "2025-06-21T12:01:00Z",
5  "labels": ["type:email"]
6}

If no task is available, the endpoint returns HTTP 204 No Content.

Extending a Lease

If the worker needs more time, extend the lease before it expires:

1curl -X POST "https://api.hola.cloud/schedulers/sched-a1b2c3d4-e5f6-7890-abcd-ef1234567890/tasks/task-002/extend" \
2  -H "X-API-Key: YOUR_API_KEY" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "extension": "30s"
6  }'

1POST /schedulers/sched-a1b2c3d4-e5f6-7890-abcd-ef1234567890/tasks/task-002/extend HTTP/1.1
2Host: api.hola.cloud
3X-API-Key: YOUR_API_KEY
4Content-Type: application/json
5
6{
7  "extension": "30s"
8}

Expected response:

1{
2  "lease_expires_at": "2025-06-21T12:01:30Z"
3}

Acknowledging (Deleting) a Task

After successful processing, acknowledge the task to remove it:

1curl -X DELETE "https://api.hola.cloud/schedulers/sched-a1b2c3d4-e5f6-7890-abcd-ef1234567890/tasks/task-002" \
2  -H "X-API-Key: YOUR_API_KEY"

1DELETE /schedulers/sched-a1b2c3d4-e5f6-7890-abcd-ef1234567890/tasks/task-002 HTTP/1.1
2Host: api.hola.cloud
3X-API-Key: YOUR_API_KEY

Expected response: HTTP 204 No Content.

Rescheduling a Task

Reschedule the task with a new delay or future time:

1curl -X POST "https://api.hola.cloud/schedulers/sched-a1b2c3d4-e5f6-7890-abcd-ef1234567890/tasks/task-002/reschedule" \
2  -H "X-API-Key: YOUR_API_KEY" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "delay": "5m"
6  }'

1POST /schedulers/sched-a1b2c3d4-e5f6-7890-abcd-ef1234567890/tasks/task-002/reschedule HTTP/1.1
2Host: api.hola.cloud
3X-API-Key: YOUR_API_KEY
4Content-Type: application/json
5
6{
7  "delay": "5m"
8}

Expected response:

1{
2  "id": "task-002",
3  "future": "2025-06-21T12:06:00Z"
4}

SSE Stream for Snapshots

Subscribe to task snapshots via Server-Sent Events:

1curl "https://api.hola.cloud/schedulers/sched-a1b2c3d4-e5f6-7890-abcd-ef1234567890/tasks/stream"

The stream emits events in SSE format:

1event: snapshot
2data: {"scheduler_id":"sched-a1b2c3d4-e5f6-7890-abcd-ef1234567890","generated_at":"2025-06-21T12:00:01Z","scheduled":[{"id":"task-003","future":"2025-06-21T12:01:00Z","labels":["type:image"]}],"inflight":[],"scheduled_meta":{"page":1,"per_page":25,"total":1,"total_pages":1},"inflight_meta":{"page":1,"per_page":25,"total":0,"total_pages":0},"health":{"status":"ok","ready":true,"scheduled":1,"inflight":0,"scheduler_id":"sched-a1b2c3d4-e5f6-7890-abcd-ef1234567890"}}