Events and runs
Section titled “Events and runs”Use the cron event feeds to observe managed crontab entries and job runs in real time. The Server-Sent Events and WebSocket endpoints expose the same event feed, while the run history endpoint lists the latest runs of managed jobs.
Shared event feed
Section titled “Shared event feed”The event feed covers the crontabs of the computer’s users.
| Event | Description |
|---|---|
entry_created | A managed crontab entry was created. |
entry_updated | A managed crontab entry was updated. |
entry_deleted | A managed crontab entry was deleted. |
crontab_changed | A whole crontab was replaced or edited. This event arrives after the entry events for that change. |
job_started | A managed job started. |
job_finished | A managed job finished. |
Each ordinary event’s data is the full event object, including id, time, user, type, and the fields specific to that event type.
Managed entry events carry source as one of api, expired, or external. Changes made outside the service, such as crontab -e or crontab -r, appear within about two seconds with source: external.
The types filter accepts the six comma-separated event types listed above. The lag and end events always arrive.
The replay history used by since_id holds the last 1024 events by default and is kept in memory only. A service restart loses this history, and a since_id from before the restart receives 409 HISTORY_GAP. Runs are kept on disk when possible, so a restart keeps them: a run still running at the restart is followed again, or recorded lost when its shell is gone. If the disk cannot be used, or a later write fails, runs from then on are kept in memory only and are lost on restart; runs that reached disk before stay (GET /api/v1/cron/info history_persisted says which).
Server-Sent Events
Section titled “Server-Sent Events”GET /api/v1/cron/events/sse
Section titled “GET /api/v1/cron/events/sse”Streams live crontab and managed-job events for the computer’s users as Server-Sent Events. The since_id cursor replays retained events before continuing with live events.
This endpoint accepts no request body.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
since_id | query | integer | No | Replay the retained events after this event id, then go live. Without it the stream starts with the next event. A browser EventSource reconnecting with its Last-Event-ID header resumes the same way. |
user | query | string | No | Only events about this user’s crontab and jobs. |
entry_id | query | string | No | Only events about this managed entry, including crontab_changed when it lists the entry. |
types | query | string | No | Only these event types, comma-separated: entry_created, entry_updated, entry_deleted, crontab_changed, job_started, job_finished. The lag and end events always arrive. |
Examples
Section titled “Examples”curl --no-buffer \ --header "Accept: text/event-stream" \ "https://{projectId}-{computerId}-cron-1.{server}.computers.hoody.com/api/v1/cron/events/sse?user=www-data"import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-cron-1.{server}.computers.hoody.com' });
await client.cron.events.stream({ user: 'www-data' });Responses
Section titled “Responses”Media type: text/event-stream
The response body is an event-stream string. Each event is one frame with:
event:set to the event type.id:set to the event id.data:set to the full event JSON.
For ordinary events, data includes id, time, user, type, and the type-specific fields.
An event: lag means the client fell behind the retained history, after which the stream ends. An event: end with reason: shutdown ends the stream when the service stops. Reconnect later with since_id. Keep-alive comments arrive every 15 seconds.
event: entry_createdid: 1700000000000001data: {"id":1700000000000001,"time":"2026-10-07T12:34:56Z","user":"www-data","type":"entry_created","source":"api"}
event: job_finishedid: 1700000000000002data: {"id":1700000000000002,"time":"2026-10-07T12:36:11Z","user":"www-data","type":"job_finished","outcome":"lost"}Media type: application/json
The request is rejected when since_id or Last-Event-ID is invalid, user is invalid, entry_id is invalid, or types contains an unsupported value. The body fields are code and message, both required strings, and the optional nullable details string.
{ "code": "INVALID_CURSOR", "details": "since_id=\"abc\"", "message": "since_id (or Last-Event-ID) must be a whole number: the id of an event received"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
INVALID_USER | Invalid user | The user parameter failed validation. | Provide a valid system username. |
INVALID_ID | Invalid id | The entry_id filter is not a UUID, a # hoody-cron: line of a crontab request body holds two id fields, or two managed entries of a crontab body share an id. | Use the id returned when the entry was created or listed. Give each managed entry of a crontab body its own id. |
INVALID_CURSOR | Invalid cursor | since_id or the Last-Event-ID header is not a whole number, is given twice, or the before parameter of GET /api/v1/cron/runs is not an RFC 3339 time. | Pass the id of the last event received, or reconnect without since_id. Pass before as an RFC 3339 time such as the started_at of a run. |
INVALID_FILTER | Invalid filter | types names an event that is not an event type, is given twice, or the key parameter of GET /api/v1/cron/runs is not 1 to 255 visible ASCII characters. | Use a comma-separated list of entry_created, entry_updated, entry_deleted, crontab_changed, job_started, and job_finished. Pass key as the Idempotency-Key of a request. |
Media type: application/json
Events after since_id are no longer retained. The body fields are code and message, both required strings, and the optional nullable details string.
{ "code": "HISTORY_GAP", "details": "{\"since_id\":1700000000000000,\"oldest_available_id\":1700000000000500,\"newest_available_id\":1700000000001523}", "message": "Events after since_id are no longer retained; reconnect without since_id"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
HISTORY_GAP | History gap | Events after since_id are no longer kept. The history is in memory, holds only recent events, and is lost when the service restarts. The details field contains the available ids. | Reconnect without since_id, and read the current entries and runs again. |
Media type: application/json
The service already has its maximum number of event streams open. SSE and WebSocket streams count toward the same limit. The body fields are code and message, both required strings, and the optional nullable details string.
{ "code": "MAX_CLIENTS_REACHED", "details": "max_stream_clients=64", "message": "Too many event streams are open"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
MAX_CLIENTS_REACHED | Too many streams | The service already has its maximum number of event streams open across SSE and WebSocket connections. | Close a stream you no longer read, or retry later. |
WebSocket events
Section titled “WebSocket events”GET /api/v1/cron/events/ws
Section titled “GET /api/v1/cron/events/ws”Streams live crontab and managed-job events for the computer’s users over WebSocket. The since_id cursor replays retained events before continuing with live events.
This endpoint accepts no request body.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
since_id | query | integer | No | Replay the retained events after this event id, then go live. Without it the stream starts with the next event. |
user | query | string | No | Only events about this user’s crontab and jobs. |
entry_id | query | string | No | Only events about this managed entry, including crontab_changed when it lists the entry. |
types | query | string | No | Only these event types, comma-separated: entry_created, entry_updated, entry_deleted, crontab_changed, job_started, job_finished. The lag and end events always arrive. |
Examples
Section titled “Examples”curl --http1.1 --include --no-buffer \ --header "Connection: Upgrade" \ --header "Upgrade: websocket" \ --header "Sec-WebSocket-Version: 13" \ --header "Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==" \ "https://{projectId}-{computerId}-cron-1.{server}.computers.hoody.com/api/v1/cron/events/ws?user=www-data"import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-cron-1.{server}.computers.hoody.com' });
await client.cron.events.connect({ user: 'www-data' });Responses
Section titled “Responses”Media type: none
The 101 response carries no body by definition.
The server sends one JSON text frame per event, with its type. A lag frame means the client fell behind the retained history and is followed by close code 4409. When the service stops, the server sends {"type":"end","reason":"shutdown"} and closes with code 1012. Reconnect later with since_id.
Frames sent by the client are ignored. The server pings every 20 seconds and closes a peer that misses a pong.
Media type: application/json
The request is rejected when since_id, user, entry_id, or types is invalid. The body fields are code and message, both required strings, and the optional nullable details string.
{ "code": "INVALID_CURSOR", "details": "since_id=\"abc\"", "message": "since_id (or Last-Event-ID) must be a whole number: the id of an event received"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
INVALID_USER | Invalid user | The user parameter failed validation. | Provide a valid system username. |
INVALID_ID | Invalid id | The entry_id filter is not a UUID, a # hoody-cron: line of a crontab request body holds two id fields, or two managed entries of a crontab body share an id. | Use the id returned when the entry was created or listed. Give each managed entry of a crontab body its own id. |
INVALID_CURSOR | Invalid cursor | since_id or the Last-Event-ID header is not a whole number, is given twice, or the before parameter of GET /api/v1/cron/runs is not an RFC 3339 time. | Pass the id of the last event received, or reconnect without since_id. Pass before as an RFC 3339 time such as the started_at of a run. |
INVALID_FILTER | Invalid filter | types names an event that is not an event type, is given twice, or the key parameter of GET /api/v1/cron/runs is not 1 to 255 visible ASCII characters. | Use a comma-separated list of entry_created, entry_updated, entry_deleted, crontab_changed, job_started, and job_finished. Pass key as the Idempotency-Key of a request. |
Media type: application/json
Events after since_id are no longer retained. The body fields are code and message, both required strings, and the optional nullable details string.
{ "code": "HISTORY_GAP", "details": "{\"since_id\":1700000000000000,\"oldest_available_id\":1700000000000500,\"newest_available_id\":1700000000001523}", "message": "Events after since_id are no longer retained; reconnect without since_id"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
HISTORY_GAP | History gap | Events after since_id are no longer kept. The history is in memory, holds only recent events, and is lost when the service restarts. The details field contains the available ids. | Reconnect without since_id, and read the current entries and runs again. |
Media type: application/json
The service already has its maximum number of event streams open. SSE and WebSocket streams count toward the same limit. The body fields are code and message, both required strings, and the optional nullable details string.
{ "code": "MAX_CLIENTS_REACHED", "details": "max_stream_clients=64", "message": "Too many event streams are open"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
MAX_CLIENTS_REACHED | Too many streams | The service already has its maximum number of event streams open across SSE and WebSocket connections. | Close a stream you no longer read, or retry later. |
Run history
Section titled “Run history”GET /api/v1/cron/runs
Section titled “GET /api/v1/cron/runs”Returns the latest runs of managed jobs, newest first, based on the reports sent by the jobs’ crontab lines. This endpoint accepts no request body.
The service keeps up to 500 runs that are still running. A scheduled job that starts while 500 runs are already running still runs but is not listed. Run now has its own limit of 16 simultaneous runs by default. For each entry, the service keeps the last 50 ended runs from the last 30 days, with at most 10,000 ended runs across all entries. The history file is capped at 5 MiB, and the oldest ended runs are dropped first.
Runs are kept on disk when possible, so a restart keeps them: a run still running at the restart is followed again, or recorded lost when its shell is gone. If the disk cannot be used, or a later write fails, runs from then on are kept in memory only and are lost on restart; runs that reached disk before stay (GET /api/v1/cron/info history_persisted says which).
Raw lines and entries in a crontab whose SHELL is not a POSIX shell have no scheduled runs listed. Run now runs of managed entries are listed.
In the Hub, open Schedules and select a managed schedule: its History section shows the reported runs.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
user | query | string | No | Only runs of this user’s jobs. |
entry_id | query | string | No | Only runs of this managed entry. |
run_id | query | string | No | Only the run with this id. |
key | query | string | No | Only the run started by the Run now request with this Idempotency-Key, and that request’s receipt. |
before | query | string | No | Only runs that started before this RFC 3339 time. Pass the started_at of the last run received to request the next page. |
limit | query | integer | No | Runs to return, newest first. Default: 50. Maximum: 200. |
Examples
Section titled “Examples”curl --get \ --url "https://{projectId}-{computerId}-cron-1.{server}.computers.hoody.com/api/v1/cron/runs" \ --data-urlencode "user=www-data" \ --data-urlencode "limit=20"import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-cron-1.{server}.computers.hoody.com' });
const runs = await client.cron.runs.list({ user: 'www-data', limit: 20 });const latestRun = runs.data.runs[0];The SDK result has { statusCode, message, data }. The runs.data object contains the receipt and runs fields.
Responses
Section titled “Responses”Media type: application/json
The response returns the latest managed-job runs, newest first.
| Field | Type | Required | Description |
|---|---|---|---|
receipt | object or null | No | The Run now receipt associated with a key. It is present only when key is used, and its state is unknown for a key the service does not hold. |
runs | array | Yes | The matching runs, newest first. |
Each item in runs has the following fields:
| Field | Type | Required | Description |
|---|---|---|---|
duration_ms | integer or null | No | The run duration in milliseconds. Minimum: 0. |
entry_id | string | Yes | The managed entry’s UUID. |
exit_code | integer or null | No | The command’s exit status. It is null while running and for a lost run. |
finished_at | string or null | No | The RFC 3339 time when the run finished. |
key | string or null | No | The Idempotency-Key of the request that started a manual run. It is null for a timer run. |
pid | integer | Yes | The process id of the job’s shell. Minimum: 0. |
run_id | string | Yes | The run’s UUID. |
started_at | string | Yes | The RFC 3339 time when the run started. |
status | string | Yes | The run status: running, finished, or lost. A run remains running until its line reports the end or its shell exits without that report. |
trigger | string | No | What started the run: timer for the cron daemon or manual for a Run now request. |
user | string | Yes | The user whose job produced the run. |
A receipt contains these fields:
| Field | Type | Required | Description |
|---|---|---|---|
entry_id | string or null | No | The managed entry’s UUID. It is null when the service holds no receipt for this key. A receipt whose start could not be confirmed after a restart can be unknown and still carry this field. |
key | string | Yes | The Run now request’s Idempotency-Key. |
reserved_at | string or null | No | The RFC 3339 time when the key was reserved. It is null when the service holds no receipt for this key. A receipt whose start could not be confirmed after a restart can be unknown and still carry this field. |
run_id | string or null | No | The UUID of the run started by the request. It is null until the run starts. |
started_at | string or null | No | The RFC 3339 time when the command started. It is null until the run starts. |
state | string | Yes | The request state: reserved, accepted, running, completed, failed, or unknown. The accepted, running, and completed states prove that the command started. The reserved and unknown states mean that it may have run. |
user | string or null | No | The entry’s user. It is null when the service holds no receipt for this key. A receipt whose start could not be confirmed after a restart can be unknown and still carry this field. |
Run now receipts are kept for 24 hours.
{ "runs": [ { "duration_ms": null, "entry_id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8", "exit_code": null, "finished_at": null, "key": "deploy-20261007-001", "pid": 4251, "run_id": "6ba7b811-9dad-11d1-80b4-00c04fd430c8", "started_at": "2026-10-07T12:36:10Z", "status": "running", "trigger": "manual", "user": "www-data" }, { "duration_ms": 1250, "entry_id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8", "exit_code": 0, "finished_at": "2026-10-07T12:34:57.250Z", "key": null, "pid": 4242, "run_id": "550e8400-e29b-41d4-a716-446655440000", "started_at": "2026-10-07T12:34:56Z", "status": "finished", "trigger": "timer", "user": "www-data" } ]}Media type: application/json
The request is rejected when user, entry_id, run_id, before, key, or limit is invalid. The body fields are code and message, both required strings, and the optional nullable details string.
{ "code": "INVALID_PAGINATION", "details": "limit=\"0\"", "message": "Limit must be between 1 and 200"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
INVALID_USER | Invalid user | The user parameter failed validation. | Provide a valid system username. |
INVALID_ID | Invalid id | The entry_id or run_id filter is not a UUID, a # hoody-cron: line of a crontab request body holds two id fields, or two managed entries of a crontab body share an id. | Use the id returned when the entry was created or listed. Give each managed entry of a crontab body its own id. |
INVALID_PAGINATION | Invalid pagination | The limit value is not a whole number from 1 to 200, or it is given more than once. The details field says which. This operation has no page parameter. | Use a single limit between 1 and 200. To read older runs, pass before. |
INVALID_CURSOR | Invalid cursor | since_id or the Last-Event-ID header is not a whole number, is given twice, or the before parameter of GET /api/v1/cron/runs is not an RFC 3339 time. | Pass the id of the last event received, or reconnect without since_id. Pass before as an RFC 3339 time such as the started_at of a run. |
INVALID_FILTER | Invalid filter | types names an event that is not an event type, is given twice, or the key parameter of GET /api/v1/cron/runs is not 1 to 255 visible ASCII characters. | Use a comma-separated list of entry_created, entry_updated, entry_deleted, crontab_changed, job_started, and job_finished. Pass key as the Idempotency-Key of a request. |