Logs
Covers 2 API operations in the logs category.
| Method | Path | Description |
|---|---|---|
| GET | /v1/orgs/{orgSlug}/projects/{projectName}/logs | Live tail of worker output (runlot logs) |
| GET | /v1/orgs/{orgSlug}/projects/{projectName}/logs/history | Stored worker output (runlot logs --since) |
GET /v1/orgs/{orgSlug}/projects/{projectName}/logs
Streams your worker's recent output live. The response is text/x-ndjson, one
LogEvent per line: first the last tail buffered lines, then, if follow is set,
new lines until you disconnect. A ping arrives every 15 seconds, which keeps proxies
from closing an idle connection and lets you tell whether the stream is still alive.
This is the live view, and it only holds the most recent output — up to 2,000
lines or 1 MiB, cleared when the worker's process is replaced. For anything older,
ask …/logs/history, which is stored separately and survives restarts.
Requires member or higher. Read-only, so it leaves no audit event.
operationId tailLogs
| Parameter | Location | Required | Type | Description |
|---|---|---|---|---|
tail | query | No | integer | Number of buffer lines to send first. Capped at 2000 |
follow | query | No | boolean | Whether to keep streaming new lines after the buffer is fully sent |
level | query | No | string | Keep lines at or above this level (debug < log = info < warn < error). A JSON line's level field counts; otherwise stderr is error and stdout log. Applied on the node; tail counts matching lines |
source | query | No | string | Keep one stream |
q | query | No | string | Keep lines containing this text, case-insensitively |
requestId | query | No | string | Keep lines that mention this request ID |
format | query | No | string | json sends each line as a LogRecord (the stored event's shape) instead of a LogEvent; pings and the end event are unchanged |
| Status code | Description | Response body |
|---|---|---|
| 200 | NDJSON stream — one LogEvent per line | LogEvent |
| 403 | — | — |
| 404 | code is not_found when the organization or project does not exist, and no_deployment when the project exists but has never been deployed — there is nothing to stream until the first deploy. | Error |
| 409 | Nothing is running to stream from right now. code is either no_home_node — no process is running for this project — or suspended. | Error |
| 502 | The project's runtime is not responding. code is node_unreachable | Error |
GET /v1/orgs/{orgSlug}/projects/{projectName}/logs/history
Searches stored log lines. Unlike the live tail this does not reach the running worker, so it answers for a project that is cold, parked, or has moved since the lines were written.
Retention is by plan: Free keeps 3 days, Pro keeps 7 days. After that the lines are deleted and cannot be recovered — ship anything you need to keep to your own store from the worker.
There is a daily cap per project: Free 200,000 lines/day, Pro 2,000,000
lines/day, counted on the UTC day. Past it the live tail carries on unchanged
and storing stops, with one runlot-stream line saying so:
runlot: daily log cap reached (200000 lines); further lines today are dropped.
Newest first, keyset-paginated: pass the cursor from a response back to get the
next page. An absent cursor in the response means there is nothing older.
Requires member or higher, the same role as the live tail. Read-only, so it does not leave an audit event.
operationId getLogHistory
| Parameter | Location | Required | Type | Description |
|---|---|---|---|---|
since | query | No | string | Oldest line to return (RFC3339). Omit for everything still kept |
until | query | No | string | Newest line to return (RFC3339) |
q | query | No | string | Plain substring, matched case-insensitively against the line. It is not a regular expression — % and _ match themselves. |
stream | query | No | string | Narrow to one stream. Omit for all three |
limit | query | No | integer | Lines per page. Capped at 1000 |
cursor | query | No | string | The cursor of the previous page |
| Status code | Description | Response body |
|---|---|---|
| 200 | One page, newest first | LogHistoryPage |
| 400 | since/until is not RFC3339, stream is not one of the three, or the cursor is unreadable | Error |
| 403 | — | — |
| 404 | The organization or project does not exist | Error |