---
audience: developer
summary: ARQ job submission, status, observability, scheduled tasks (cron).
title: Queue and scheduled tasks API
path: reference/api/queue-and-scheduled-tasks
status: published
---

# Queue and scheduled tasks API

21 endpoints (16 queue + 1 observability + 4 scheduled).

## Queue (low-level)

A thin wrapper over ARQ for clients that need to enqueue work
directly. Most apps shouldn't — prefer the higher-level endpoints
that enqueue internally.

| Method | Path | Purpose |
|---|---|---|
| `POST` | `/v1/queue/jobs` | Submit a job. |
| `GET` | `/v1/queue/jobs/{job_id}` | Status. |
| `POST` | `/v1/queue/jobs/{job_id}/cancel` | Try to cancel. |
| `GET` | `/v1/queue/jobs` | List your jobs. |
| `GET` | `/v1/queue/depth` | Queue depth metrics. |
| `POST` | `/v1/queue/hitl/{request_id}/approve` | Approve a HITL-gated job. |
| `POST` | `/v1/queue/hitl/{request_id}/reject` | Reject. |
| `GET` | `/v1/queue/hitl` | List pending HITL requests. |
| `GET` | `/v1/queue/correlation/{correlation_id}` | All jobs sharing a correlation id. |
| ... | (additional admin / introspection paths under `/v1/queue/`) | ... |

HITL = "human-in-the-loop". Some plugin tool calls are flagged for
approval; they enqueue a queued job that waits for human approval
before running.

## Observability

| Method | Path | Purpose |
|---|---|---|
| `GET` | `/v1/queue/observability/...` | Aggregated metrics for the queue (admin). |

## Scheduled tasks

| Method | Path | Purpose |
|---|---|---|
| `GET` | `/v1/scheduled-tasks` | List your scheduled tasks. |
| `POST` | `/v1/scheduled-tasks` | Create. |
| `PATCH` | `/v1/scheduled-tasks/{task_id}` | Update. |
| `DELETE` | `/v1/scheduled-tasks/{task_id}` | Remove. |

### POST body

```jsonc
{
  "name": "Weekly status update",
  "schedule": "0 9 * * MON",       // crontab
  "timezone": "Europe/Amsterdam",
  "action": "send_message",
  "args": {
    "room_id": "room-…",
    "content": { "msgtype": "swp.text", "body": "Monday status check" }
  },
  "enabled": true
}
```

Supported actions:

- `send_message` — bot-style scheduled posts.
- `trigger_ai` — engage an AI in a room with a prompt.
- `run_query` — execute a stored notes query and post the results.

Custom actions can be plugin-provided.