# Events and Runs **Page:** api/cron/events [Download Raw Markdown](./api/cron/events.md) --- # 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. These routes use the computer's cron URL. The computer's proxy permission rules determine who may call them. Do not send a Hoody account token to this host. ## 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. Job events come from the crontab line of an enabled managed entry, which reports its own start and end. Scheduled runs of raw lines written outside the service and scheduled runs of entries in a crontab whose `SHELL` is not a POSIX shell are not reported. Run now of a managed entry is always recorded and sends job events. If a job's shell exits without reporting its end, such as after `exec` or when the job is killed, the job finishes with `outcome: lost`. 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 ### `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 | 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 ```bash 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" ``` ```typescript 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 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. ```text/event-stream 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"} ``` 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. ```json { "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. ```json { "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. ```json { "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 ### `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 | 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 ```bash 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" ``` ```typescript 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 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. ```json { "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. ```json { "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. ```json { "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 ### `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 | 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 ```bash 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" ``` ```typescript 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 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. ```json { "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. ```json { "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. |