Skip to content

Beta: these docs are still being updated. The next full update is on 18 November at 8 PM UTC. Docs in beta. Full update 18 Nov, 8 PM UTC.

Hoody.com

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.

The event feed covers the crontabs of the computer’s users.

EventDescription
entry_createdA managed crontab entry was created.
entry_updatedA managed crontab entry was updated.
entry_deletedA managed crontab entry was deleted.
crontab_changedA whole crontab was replaced or edited. This event arrives after the entry events for that change.
job_startedA managed job started.
job_finishedA 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).

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.

NameInTypeRequiredDescription
since_idqueryintegerNoReplay 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.
userquerystringNoOnly events about this user’s crontab and jobs.
entry_idquerystringNoOnly events about this managed entry, including crontab_changed when it lists the entry.
typesquerystringNoOnly these event types, comma-separated: entry_created, entry_updated, entry_deleted, crontab_changed, job_started, job_finished. The lag and end events always arrive.
Terminal window
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"

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_created
id: 1700000000000001
data: {"id":1700000000000001,"time":"2026-10-07T12:34:56Z","user":"www-data","type":"entry_created","source":"api"}
event: job_finished
id: 1700000000000002
data: {"id":1700000000000002,"time":"2026-10-07T12:36:11Z","user":"www-data","type":"job_finished","outcome":"lost"}

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.

NameInTypeRequiredDescription
since_idqueryintegerNoReplay the retained events after this event id, then go live. Without it the stream starts with the next event.
userquerystringNoOnly events about this user’s crontab and jobs.
entry_idquerystringNoOnly events about this managed entry, including crontab_changed when it lists the entry.
typesquerystringNoOnly these event types, comma-separated: entry_created, entry_updated, entry_deleted, crontab_changed, job_started, job_finished. The lag and end events always arrive.
Terminal window
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"

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.

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.

NameInTypeRequiredDescription
userquerystringNoOnly runs of this user’s jobs.
entry_idquerystringNoOnly runs of this managed entry.
run_idquerystringNoOnly the run with this id.
keyquerystringNoOnly the run started by the Run now request with this Idempotency-Key, and that request’s receipt.
beforequerystringNoOnly runs that started before this RFC 3339 time. Pass the started_at of the last run received to request the next page.
limitqueryintegerNoRuns to return, newest first. Default: 50. Maximum: 200.
Terminal window
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"

Media type: application/json

The response returns the latest managed-job runs, newest first.

FieldTypeRequiredDescription
receiptobject or nullNoThe 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.
runsarrayYesThe matching runs, newest first.

Each item in runs has the following fields:

FieldTypeRequiredDescription
duration_msinteger or nullNoThe run duration in milliseconds. Minimum: 0.
entry_idstringYesThe managed entry’s UUID.
exit_codeinteger or nullNoThe command’s exit status. It is null while running and for a lost run.
finished_atstring or nullNoThe RFC 3339 time when the run finished.
keystring or nullNoThe Idempotency-Key of the request that started a manual run. It is null for a timer run.
pidintegerYesThe process id of the job’s shell. Minimum: 0.
run_idstringYesThe run’s UUID.
started_atstringYesThe RFC 3339 time when the run started.
statusstringYesThe run status: running, finished, or lost. A run remains running until its line reports the end or its shell exits without that report.
triggerstringNoWhat started the run: timer for the cron daemon or manual for a Run now request.
userstringYesThe user whose job produced the run.

A receipt contains these fields:

FieldTypeRequiredDescription
entry_idstring or nullNoThe 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.
keystringYesThe Run now request’s Idempotency-Key.
reserved_atstring or nullNoThe 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_idstring or nullNoThe UUID of the run started by the request. It is null until the run starts.
started_atstring or nullNoThe RFC 3339 time when the command started. It is null until the run starts.
statestringYesThe 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.
userstring or nullNoThe 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"
}
]
}