Skip to content

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.

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…"
}
  • limit is 1 to 100 (default 50); a value that is not a positive integer is a 400, a larger one is clamped to 100.
  • next_cursor is opaque. Pass it back as cursor; it is null on 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 + 1 rows, whatever the size of the build history.
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_id and project_id must 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 than team_id gives an empty list.
  • status is a build status name (pending, active, running_pipeline, successful, failed, cancelled and 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.
  • kind is deploy, build_only (builds but never deploys) or package (a Package build environment). Each row carries its own kind.
  • limit is 1 to 100 (default 10); a value that is not a positive integer is a 400, a larger one is clamped to 100. next_cursor is opaque, null on 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.

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.

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.

  • status narrows to active (open plus mitigating), open, mitigating or resolved. Anything else is a 400.
  • Each item is the incident row plus environment: { id, name, slug, project_id }.
  • limit and cursor behave as for builds. The order (active first, opened_at, id) is total, so paging is stable.

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-ID header: what a browser EventSource sends by itself on reconnect.
  • after_id query 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 malformed after_id is a 400.
GET /environments/{environment_id}/builds/{build_id}/logs/stream?after_id=1042

The 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.

GET /environments/{environment_id}/logs/stream?app_service_id=<service-uuid>&process=web&after_id=250

Omit 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 job tail, 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.
GET /teams/{team_id}/events/stream

One 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: 12000341
event: change
data: {"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.

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 ready with the current sequence (also its id:), the baseline to resume from if the connection drops before any change.
  • Send Last-Event-ID (a browser EventSource does this by itself) or after_sequence to resume. The header wins when both are sent; a malformed after_sequence is a 400 and a malformed header is ignored. The server replays the team’s missed events in order, then sends ready with resumed: true and replayed: <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 reset with the current sequence and a reason (resume_window_exceeded or resume_out_of_range) and continues live from there. The client must refetch its state.
  • A : heartbeat comment is sent every 15 seconds. The stream ends after 10 minutes with a final bye event (reason: max_duration); reconnect with the last id. bye also carries access_revoked (the user left the team; membership is re-checked every minute), shutdown (the API is restarting), slow_consumer and error.
  • 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.
GET /teams/{team_id}/systems

Every 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 }
}
  • health is the worst state among the System’s environments (unhealthy, degraded, deploying, unknown, healthy); a System without environments is unknown, never healthy. health_reason is the reason of the worst environment.
  • reason_code names 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_unhealthy or runtime_finding. It is null when 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 is healthy with delivery_failed_previous_serving.
  • An environment that Host sees no workload for has no_runtime_state and reads unknown. 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 is unhealthy when 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.
  • serving and delivery split that into two answers. serving.state is the worst answer among the production environments (serving.basis is production_members, or all_members while none is marked production, or none); delivery.state is failed, in_progress, unknown or succeeded across all environments. Each environment carries role (production, staging, development, preview or null), role_source (set or derived), serving, delivery and delivery_reason. A failed staging deploy makes delivery failed and leaves serving as it was.
  • last_activity_at is the newest Activity item of the System’s environments in the last 30 days, or null.
  • last_deployment is the newest current build among the System’s environments; an environment’s own is its current build.
  • environments are worst first. health_counts count 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.