In Selenium Grid 4, what does the /status endpoint return and what does its ready flag mean?

juniormust knowfreq 66%

answer

One GET tells you the grid's mood
The reply is a JSON envelope
A boolean, a message, a node list
It asks whether any slot is free
A fully booked grid is not ready

basics

~20 s

Selenium Grid's /status returns JSON holding a boolean ready flag, a message, and a nodes array describing every registered node and its slots. Ready is true only when at least one node is up and has a free slot.

solid answer

~40 s

A GET on a Selenium 4 Grid's /status — for example http://localhost:4444/status — returns a WebDriver-style envelope: a value object holding ready, message and nodes. The router computes ready as at least one registered node is UP and still has a free slot, so it answers "can a session start right now", not "is the grid healthy": a perfectly sound but fully booked grid reports ready: false with Selenium Grid not ready.. Each nodes entry carries id, uri, maxSessions, sessionTimeout, heartbeatPeriod, availability, version, osInfo and a slots array, where each slot has a stereotype and either a session object or null. The HTTP status stays 200 either way; the separate /readyz endpoint is the one that returns 503 when the grid's own components are not up.

A `GET` on a Selenium 4 Grid's `/status` — for example `http://localhost:4444/status` — returns a WebDriver-style envelope: a `value` object holding `ready`, `message` and `nodes`. The router computes `ready` as *at least one registered node is `UP` and still has a free slot*, so it answers "can a session start right now", not "is the grid healthy": a perfectly sound but fully booked grid reports `ready: false` with `Selenium Grid not ready.`. Each `nodes` entry carries `id`, `uri`, `maxSessions`, `sessionTimeout`, `heartbeatPeriod`, `availability`, `version`, `osInfo` and a `slots` array, where each slot has a `stereotype` and either a session object or `null`. The HTTP status stays `200` either way; the separate `/readyz` endpoint is the one that returns `503` when the grid's own components are not up.

go deeper

for a junior

Be ready to name the endpoint, show the curl, and say what ready means. Knowing that a full grid reports ready false is enough to stop you from reporting a healthy grid as broken.

for a middle

Explain the mechanics: ready is one anyMatch over registered nodes for UP plus a free slot, the HTTP status is always 200, and slots with a null session are the free ones.

for a senior

Show how you use it in operations: parse value.ready rather than the status code, watch the nodes array for missing registrations, and distinguish saturation from a distributor read timeout.

for a principal

Own the policy question of what readiness should gate. Decide whether a capacity signal belongs in a deployment gate at all, and where a capability-blind boolean stops being a useful contract for teams sharing one grid.

What the endpoint is

Every Selenium 4 Grid — started as standalone, as a hub, or as a separate router — serves a small read-only readiness document at GET /status on its public HTTP port. It is the cheapest question you can ask a grid: no client library, no session, one request. Selenium deliberately exempts /status (and /readyz) from the Origin and Content-Type header checks it applies to session traffic, so a bare curl or a container health probe reaches it without setting any headers.

The shape of the document

The body is a WebDriver-style envelope: one top-level value object holding three keys.

ready — a boolean, and the whole point of the endpoint.
message — either Selenium Grid ready. or Selenium Grid not ready., a human-readable echo of ready.
nodes — an array with one entry per node the distributor currently knows about.

json

{
  "value": {
    "ready": true,
    "message": "Selenium Grid ready.",
    "nodes": [
      {
        "id": "4b2f...",
        "uri": "http://10.0.0.7:5555",
        "maxSessions": 4,
        "sessionTimeout": 300000,
        "heartbeatPeriod": 60000,
        "availability": "UP",
        "version": "4.49.0",
        "osInfo": { "arch": "amd64", "name": "Linux", "version": "6.8.0" },
        "slots": [
          { "id": {}, "lastStarted": "1970-01-01T00:00:00Z",
            "session": null, "stereotype": { "browserName": "chrome" } }
        ]
      }
    ]
  }
}

What `ready` actually computes

The router builds ready with a single rule: at least one registered node is UP and still has a free slot. Concretely:

Ask the distributor for its status — every node it has registered, with that node's slots.
For each node, check availability == UP and that the count of slots holding a session is below the node's maxSessions.
If any node passes both, ready is true; otherwise it is false.

Three things ready therefore is not:

It is not "every node is healthy". One UP node with a spare slot makes the whole grid ready, even when its neighbours are DOWN.
It is not "the queue is empty". Queue depth never enters the calculation.
It is not "a slot matching your capabilities is free". ready is capability-blind: it counts free slots, never their stereotypes.

Two mechanical details bite people. First, the HTTP status is always 200, including when ready is false — the verdict lives in the body, so a probe that only looks at the status code learns nothing. Second, the router gives the distributor two seconds to answer; on timeout it returns ready: false with Unable to read distributor status. and no nodes key at all, which is a very different situation from a merely busy grid.

Reading the `nodes` array

Field	What it tells you
`id`, `uri`	which node this is and where the router reaches it
`availability`	`UP`, `DRAINING` or `DOWN`
`maxSessions`	how many sessions this node will run at once
`slots`	one entry per slot, each with a `stereotype` and a `session`
`sessionTimeout`, `heartbeatPeriod`	both reported in milliseconds
`version`, `osInfo`	node build and host platform, useful for spotting a stale node

A slot whose session is null is free; a slot with a session object is busy. Counting free slots per stereotype is how you turn /status from a yes/no into an actual capacity picture.

`/status` versus `/readyz`

	`/status`	`/readyz`
Answers	can a session start right now?	did this process's own components come up?
Body	JSON `value` envelope	short text, e.g. `Standalone is true`
HTTP status	always `200`	`200` when ready, `503` when not
Sees nodes	yes, the whole list	no

/readyz is the liveness signal for the grid process; /status is the capacity signal for the grid fleet. Confusing them is the classic mistake: a grid whose components are all healthy but whose slots are all busy reports readyz 200 and /status ready: false at the same instant, and both are correct.

A worked read

A team runs a nightly regression over a construction-permit checklist application against a grid of three nodes. The run stalls, and /status shows ready: false. The nodes array still lists all three nodes with availability: UP, and every slot carries a session object. Nothing is broken — the grid is simply full, and the pending requests are sitting in the session queue waiting for a checklist test to release a slot. Had the array instead come back empty, the diagnosis would be the opposite: the distributor knows about no nodes at all, so nothing has registered.

## What the endpoint is Every **Selenium 4 Grid** — started as `standalone`, as a `hub`, or as a separate `router` — serves a small read-only readiness document at `GET /status` on its public HTTP port. It is the cheapest question you can ask a grid: no client library, no session, one request. Selenium deliberately exempts `/status` (and `/readyz`) from the Origin and Content-Type header checks it applies to session traffic, so a bare `curl` or a container health probe reaches it without setting any headers. ## The shape of the document The body is a **WebDriver-style envelope**: one top-level `value` object holding three keys. - `ready` — a boolean, and the whole point of the endpoint. - `message` — either `Selenium Grid ready.` or `Selenium Grid not ready.`, a human-readable echo of `ready`. - `nodes` — an array with one entry per node the **distributor** currently knows about. ```json { "value": { "ready": true, "message": "Selenium Grid ready.", "nodes": [ { "id": "4b2f...", "uri": "http://10.0.0.7:5555", "maxSessions": 4, "sessionTimeout": 300000, "heartbeatPeriod": 60000, "availability": "UP", "version": "4.49.0", "osInfo": { "arch": "amd64", "name": "Linux", "version": "6.8.0" }, "slots": [ { "id": {}, "lastStarted": "1970-01-01T00:00:00Z", "session": null, "stereotype": { "browserName": "chrome" } } ] } ] } } ``` ## What `ready` actually computes The router builds `ready` with a single rule: **at least one registered node is `UP` and still has a free slot.** Concretely: 1. Ask the distributor for its status — every node it has registered, with that node's slots. 2. For each node, check `availability == UP` and that the count of slots holding a session is below the node's `maxSessions`. 3. If any node passes both, `ready` is `true`; otherwise it is `false`. Three things `ready` therefore is **not**: - It is **not** "every node is healthy". One `UP` node with a spare slot makes the whole grid `ready`, even when its neighbours are `DOWN`. - It is **not** "the queue is empty". Queue depth never enters the calculation. - It is **not** "a slot matching *your* capabilities is free". `ready` is **capability-blind**: it counts free slots, never their stereotypes. Two mechanical details bite people. First, the HTTP status is **always 200**, including when `ready` is `false` — the verdict lives in the body, so a probe that only looks at the status code learns nothing. Second, the router gives the distributor two seconds to answer; on timeout it returns `ready: false` with `Unable to read distributor status.` and **no `nodes` key at all**, which is a very different situation from a merely busy grid. ## Reading the `nodes` array | Field | What it tells you | |---|---| | `id`, `uri` | which node this is and where the router reaches it | | `availability` | `UP`, `DRAINING` or `DOWN` | | `maxSessions` | how many sessions this node will run at once | | `slots` | one entry per slot, each with a `stereotype` and a `session` | | `sessionTimeout`, `heartbeatPeriod` | both reported in **milliseconds** | | `version`, `osInfo` | node build and host platform, useful for spotting a stale node | A slot whose `session` is `null` is **free**; a slot with a session object is **busy**. Counting free slots per stereotype is how you turn `/status` from a yes/no into an actual capacity picture. ## `/status` versus `/readyz` | | `/status` | `/readyz` | |---|---|---| | Answers | can a session start right now? | did this process's own components come up? | | Body | JSON `value` envelope | short text, e.g. `Standalone is true` | | HTTP status | always `200` | `200` when ready, `503` when not | | Sees nodes | yes, the whole list | no | `/readyz` is the liveness signal for the grid **process**; `/status` is the capacity signal for the grid **fleet**. Confusing them is the classic mistake: a grid whose components are all healthy but whose slots are all busy reports `readyz` 200 and `/status` `ready: false` at the same instant, and both are correct. ## A worked read A team runs a nightly regression over a **construction-permit checklist** application against a grid of three nodes. The run stalls, and `/status` shows `ready: false`. The `nodes` array still lists all three nodes with `availability: UP`, and every slot carries a session object. Nothing is broken — the grid is simply full, and the pending requests are sitting in the session queue waiting for a checklist test to release a slot. Had the array instead come back empty, the diagnosis would be the opposite: the distributor knows about no nodes at all, so nothing has registered.

Your grid reports ready false but every node shows availability UP — what happened?
`ready` is `true` only while some `UP` node still has a free slot. If every slot on every node holds a session, the grid is saturated rather than broken: `/status` says `ready: false` and `Selenium Grid not ready.` while each node's `availability` stays `UP`. New requests wait in the session queue until a slot frees.
How does a node's own /status differ from the router's?
A Selenium 4 node serves `/status` on its own port and reports only itself. Its `ready` is that node's free-slot check, its `message` is `Ready` or `No free slots available`, and it adds a `registered` boolean saying whether the node has joined the grid, plus a `node` object with its slots. The router's `/status` instead aggregates every node the distributor knows about.
Why is a 200 response from /status a poor health check on its own?
The router returns `200` whether `ready` is `true` or `false`, so a probe that inspects only the status code cannot tell a working grid from a saturated one. Parse the body and assert `value.ready`. If the distributor cannot be read within two seconds, the response is `ready: false` with `Unable to read distributor status.` and no `nodes` key.

It is the sign at a permitting office counter: it tells you whether a window is open right now, not whether the building is on fire.

saying these in an interview costs you the question

Reads ready false as a crashed grid rather than a fully booked one
Thinks ready true guarantees a free slot for the requested browser
Expects /status to answer HTTP 503 while ready is false
Looks for queued session requests inside the /status document
Forgets the payload is wrapped in a value envelope

In Selenium Grid 4, what does the /status endpoint return and what does its ready flag mean?

§ answer

basics

solid answer

§ go deeper

▾level notes4 levels

▾deep dive~4 min

What the endpoint is

The shape of the document

What ready actually computes

Reading the nodes array

/status versus /readyz

A worked read

▾common follow-ups3 questions

▾analogy~10 s

▾red flags5 flags

What the endpoint is

The shape of the document

What ready actually computes

Reading the nodes array

/status versus /readyz

A worked read

answer

go deeper

What `ready` actually computes

Reading the `nodes` array

`/status` versus `/readyz`

What `ready` actually computes

Reading the `nodes` array

`/status` versus `/readyz`