Lists and Live Updates
These endpoints give a dashboard or terminal client what it needs to show a whole project or team without one request per environment. All of them are in the API reference.
Builds across a project
Section titled “Builds across a project”GET /projects/{project_id}/builds?limit=50&cursor=...Recent builds across every environment of the project, newest first. project_id is a UUID or the project slug. Any
team member with environment:read (every role from viewer up) can call it; a project the caller cannot see is a 404.
Each item is the same shape as an item of GET /environments/{environment_id}/builds (the build row, build_status,
user, repository and jobs) plus the environment it belongs to:
{ "builds": [ { "id": "…", "environment_id": "…", "started_at": "2026-10-07 12:00:00+00", "build_status": { "name": "successful" }, "jobs": [], "environment": { "id": "…", "name": "staging", "slug": "staging" } } ], "next_cursor": "MjAyNi0xMC0wNyAxMjowMDowMCswMHw…"}limitis 1 to 100 (default 50); a value that is not a positive integer is a 400, a larger one is clamped to 100.next_cursoris opaque. Pass it back ascursor; it isnullon the last page. Builds are ordered by(started_at, id), so a build started while you page never repeats or skips one you already saw. A build that has not started yet (waiting for a customer runner) comes first.- The work is bounded by the number of environments times
limit + 1rows, whatever the size of the build history.
Builds across an Organization
Section titled “Builds across an Organization”GET /builds?team_id=...&project_id=...&status=failed&kind=package&limit=20&cursor=...The builds of every team the caller belongs to, newest first: what a Build & Deploy list reads. All filters are optional and combine.
team_idandproject_idmust belong to a team the caller is a member of. Otherwise the answer is a 403, never an empty list, so a wrong id is not mistaken for “no builds”. A project in another team thanteam_idgives an empty list.statusis a build status name (pending,active,running_pipeline,successful,failed,cancelledand so on), or up to 20 names separated by commas to match any of them (status=failed,errored,timed_out); a name that is not a build status is a 400.kindisdeploy,build_only(builds but never deploys) orpackage(a Package build environment). Each row carries its ownkind.limitis 1 to 100 (default 10); a value that is not a positive integer is a 400, a larger one is clamped to 100.next_cursoris opaque,nullon the last page, and the order(started_at, id)is total, so paging is stable. A cursor that did not come from a previous page is a 400.
Each item keeps the shape the endpoint always had (the build row, build_status, user, jobs and
repository.environment.project.team) and adds flat fields for a list row:
{ "id": "…", "number": 42, "status": "failed", "kind": "deploy", "commit": "9f2c1ab", "message": "Fix the checkout total", "started_at": "2026-11-07 12:00:00+00", "finished_at": "2026-11-07 12:03:10+00", "environment": { "id": "…", "name": "production", "slug": "production" }, "project": { "id": "…", "name": "Shop", "slug": "shop" }, "team": { "id": "…", "name": "Acme", "slug": "acme" }, "package_release": null, "verification_status": "healthy", "failure": { "stage": "build_image", "kind": "user_code", "detail": "…" }}verification_status is the post-deploy verification of the build (pending, healthy, unhealthy, unknown or
not_applicable), read from deployment_verifications in one query for the whole page, and null when none was
recorded (a build that never deployed, or one that deployed before verification existed).
package_release is set for a Package build that published a version: package, version, bump, published_at,
deprecated and release_status. failure is null unless the build recorded one, and its detail has git
credentials removed. A build row with no environment is not listed. Recent releases are read from
GET /teams/{team_id}/activity?category=deployments (see Activity of an Organization), not from this list.
Activity of an Organization
Section titled “Activity of an Organization”GET /teams/{team_id}/activity?category=imported_ci&project_id=...&since=...&limit=30&cursor=...The curated change history of the Organization, newest first, with a label, category and deep link already computed.
Any team member with team:read can call it. Categories are deployments, environments, incidents, security,
automation and imported_ci (CI runs imported from a connected provider; a Merge or Pull request run is labelled
with its number). Filters: repeat category, project_id, environment_id, system_id (a System of this team, 404
otherwise), actor_user_id, since (inclusive) and until (exclusive) as ISO timestamps. Filters are applied before
the page is cut. Imported CI items have imported_from (for example GitLab) and external_url, and are left out when
actor_user_id is set. next_cursor is null on the last page.
Incidents across a team
Section titled “Incidents across a team”GET /teams/{team_id}/incidents?status=active&limit=50&cursor=...Every incident of the team, active ones first. Open and mitigating incidents come before resolved ones, and each group
is newest-opened first. The caller needs team:read and the host.incidents feature, the same as the per-environment
incident list.
statusnarrows toactive(open plus mitigating),open,mitigatingorresolved. Anything else is a 400.- Each item is the incident row plus
environment: { id, name, slug, project_id }. limitandcursorbehave as for builds. The order(active first, opened_at, id)is total, so paging is stable.
Resuming a log stream
Section titled “Resuming a log stream”Both log streams send an SSE id: with every log event, and both accept it back so a reconnect does not start over.
A client that sends nothing gets exactly the stream it got before: a full replay from the first line.
Last-Event-IDheader: what a browserEventSourcesends by itself on reconnect.after_idquery parameter: the same position for clients that cannot set the header. When both are sent the header wins. A header that is not a non-negative integer is ignored; a malformedafter_idis a 400.
Build logs
Section titled “Build logs”GET /environments/{environment_id}/builds/{build_id}/logs/stream?after_id=1042The id of a log event is the id of its build_logs row, so resuming is exact: the stream sends the logs with a
greater id, then a status event, and ends with done once the build is terminal. status and done events carry no
id, so the last id a client holds is always a log line.
Runtime logs
Section titled “Runtime logs”GET /environments/{environment_id}/logs/stream?app_service_id=<service-uuid>&process=web&after_id=250Omit app_service_id to use the environment’s default service. On Forest-managed environments, pass
job=<run-job-uuid> to tail a one-off run job’s pod; that stream ends when the command does. The job must be a run
job in the requested environment. A service from another environment returns 404.
A Grove has no log sequence and does not timestamp lines, and every new session replays the container’s log from its
beginning. The id is therefore the count of lines the Grove has sent on the connection (1, 2, 3, …), and a resume
drops that many leading lines before sending any. This is best effort:
- It is exact while the same single pod serves the process and its container log has not rotated, and for a
jobtail, which always follows one pod. - After a pod replacement, a log rotation, or with more than one Ready pod (their lines interleave in a different order every time), lines can be skipped or repeated. A client that must not miss lines should treat a resumed stream as a hint and show a “may be incomplete” marker across the reconnect.
- There is no
since=<timestamp>form: the lines carry no timestamps to filter by.
Team change stream
Section titled “Team change stream”GET /teams/{team_id}/events/streamOne Server-Sent Events connection that tells a client “something changed” in a team, so a dashboard can refetch only
what moved instead of polling every build, environment and incident. Any team member can open it (team:read).
An event is a hint, not a payload. Read the current state with the normal endpoints.
id: 12000341event: changedata: {"sequence":12000341,"kind":"build","type":"build.succeeded","status":"succeeded", "occurred_at":"2026-10-07 12:00:00+00","project_id":"…","environment_id":"…","build_id":"…", "incident_id":null,"operation_id":null,"subject_type":"build","subject_id":"…"}kind |
Ledger events behind it | status values |
|---|---|---|
build |
build.started, build.succeeded, build.failed, build.stale_cancelled |
running, succeeded, failed, cancelled |
deployment |
environment.deployed, deployment.verified, deployment.unhealthy, rollback.started, rollback.completed, rollback.degraded, release.created, release.promoted, release.reverted, release.revert_failed |
deployed, verified, unhealthy, rollback_started, rollback_completed, rollback_degraded, release_created, release_promoted, release_reverted, release_revert_failed |
incident |
incident.opened, incident.mitigated, incident.resolved, incident.dismissed |
open, mitigating, resolved |
operation |
sandbox.run.started, sandbox.run.finished, pipeline.run_completed |
running, finished, completed |
Other event types (variable changes, pipeline node events, audit events) are not announced. Operations are only
announced for the ledger events above: an operation whose status changes without writing a ledger event is not
reported, so keep a slow poll of GET /teams/{team_id}/operations where that matters.
Ordering and resuming
Section titled “Ordering and resuming”The stream reads the platform event ledger, the one append-only table that already records every state change, so there
is no second event store. Its sequence is a single gap-free counter assigned under a lock, which makes it a safe
resume cursor: the id: of each change event is that sequence and only ever increases.
- A new connection starts live. Its first event is
readywith the currentsequence(also itsid:), the baseline to resume from if the connection drops before any change. - Send
Last-Event-ID(a browserEventSourcedoes this by itself) orafter_sequenceto resume. The header wins when both are sent; a malformedafter_sequenceis a 400 and a malformed header is ignored. The server replays the team’s missed events in order, then sendsreadywithresumed: trueandreplayed: <n>, then continues live. No event is skipped or repeated. - When the gap is too large to replay (more than 500 announced events, or more than 20,000 ledger rows behind the
head) or the id is ahead of the ledger, the server sends
resetwith the currentsequenceand areason(resume_window_exceededorresume_out_of_range) and continues live from there. The client must refetch its state.
Lifetime and limits
Section titled “Lifetime and limits”- A
: heartbeatcomment is sent every 15 seconds. The stream ends after 10 minutes with a finalbyeevent (reason: max_duration); reconnect with the last id.byealso carriesaccess_revoked(the user left the team; membership is re-checked every minute),shutdown(the API is restarting),slow_consumeranderror. - At most 5 open streams per user, 200 per team and 5,000 per API process. Reaching one of those limits returns a
retryable 429 with
retryAfterSeconds: 5. Connection attempts are separately limited to 30 per minute per user (or per IP when no user identity is available) per API process; that rate-limit response is a plain 429 and does not include the retryable fields. - All open streams in an API process share one poller. It checks the ledger head once per second and reads new rows only when the head advances, so it performs at most two indexed ledger reads per tick regardless of how many clients are connected. Events are delivered only to streams of the team that owns them. A client that stops reading is dropped once more than 256 KiB is queued for it, and can resume from its last id.
Systems and their health
Section titled “Systems and their health”GET /teams/{team_id}/systemsEvery System of the Organization with what a list row needs, in one request however many Systems there are. A System is a named group of environments that run together across projects. Any member of the Organization can call it; an Organization the caller is not in is a 404.
{ "systems": [ { "id": "…", "name": "Fleet platform", "slug": "fleet-platform", "description": "The fleet API, its worker and the dashboard", "health": "unhealthy", "health_reason": "The most recent deploy failed.", "reason_code": "deploy_failed", "last_activity_at": "2027-03-01T11:00:00.000Z", "last_deployment": { "build_id": "…", "sha": "b2c3d4e…", "at": "2027-03-01T10:00:00.000Z" }, "environments": [ { "id": "…", "slug": "production", "name": null, "branch": "production", "project_id": "…", "project_name": "fleet-api", "health": "unhealthy", "health_reason": "The most recent deploy failed.", "reason_code": "deploy_failed", "last_deployment": { "build_id": "…", "sha": "b2c3d4e…", "at": "2027-03-01T10:00:00.000Z" } } ] } ], "health_counts": { "healthy": 11, "degraded": 0, "unhealthy": 1, "deploying": 0, "unknown": 1, "total": 13 }}healthis the worst state among the System’s environments (unhealthy,degraded,deploying,unknown,healthy); a System without environments isunknown, neverhealthy.health_reasonis the reason of the worst environment.reason_codenames that reason for a program:no_environments,no_runtime_state,never_deployed,rollout_in_progress,verification_failed,not_verified,deploy_failed,delivery_failed_previous_serving,reported_unhealthyorruntime_finding. It isnullwhen the System is healthy. Each environment carries its own; an environment whose newest build failed before it deployed while an earlier build is still serving ishealthywithdelivery_failed_previous_serving.- An environment that Host sees no workload for has
no_runtime_stateand readsunknown. The exception is an environment that staff have set to be observed through Groves (the Grove controllers, which Terraform applies): it serves as those Groves report, and isunhealthywhen a Grove’s controller has stopped sending heartbeats. A System whose members are not observed, but whose newest build was delivered, reads as serving what it delivered, with a reason that says the runtime is not observed. servinganddeliverysplit that into two answers.serving.stateis the worst answer among the production environments (serving.basisisproduction_members, orall_memberswhile none is marked production, ornone);delivery.stateisfailed,in_progress,unknownorsucceededacross all environments. Each environment carriesrole(production,staging,development,previewornull),role_source(setorderived),serving,deliveryanddelivery_reason. A failed staging deploy makesdeliveryfailed and leavesservingas it was.last_activity_atis the newest Activity item of the System’s environments in the last 30 days, ornull.last_deploymentis the newest current build among the System’s environments; an environment’s own is its current build.environmentsare worst first.health_countscount each environment of the Organization’s Systems once, even when it belongs to several Systems.
GET /systems/{system_id} returns the same per-environment fields, a reason_code for the System, and the environments
of one System. GET /systems/{system_id}/activity?limit=&cursor= pages the Organization’s Activity feed filtered to the
System’s environments; the filter applies in the query, so every page holds up to limit items of that System and
next_cursor is set whenever more exist. GET /systems/{system_id}/timeline?days=&limit=&cursor= is the same feed for the
last 14 days at most, with the actor of each item (the person the event names, else whoever triggered the build, source
says which), its environment and role, the owner_groups that own it and refs; it returns up to 200 items per page.
Creating, renaming and deleting a System, and adding or removing a member environment, are recorded in the Organization’s
audit log as system.created, system.updated, system.deleted, system.member_added, system.member_removed and system.member_role_set,
with the System’s id and name (and, for a member, the environment) in the event’s metadata. Adding an environment that is
already a member, or removing one that is not, records nothing. An API key limited to a single project or environment
cannot read or change a System: those requests are refused with 403.