Workers

List Workers

List workers connected to the control plane in a namespace, optionally filtered by name or key. Results are paginated.

GET https://api.rivet.dev/envoys

Examples

curl "https://api.rivet.dev/envoys?namespace=$RIVET_NAMESPACE" \
  -H "Authorization: Bearer $RIVET_TOKEN"

const endpoint = "https://api.rivet.dev";
const namespace = process.env.RIVET_NAMESPACE ?? "default";
const token = process.env.RIVET_TOKEN ?? "";

const params = new URLSearchParams({ namespace });
const response = await fetch(`${endpoint}/envoys?${params}`, {
	headers: { Authorization: `Bearer ${token}` },
});
const { envoys: workers, pagination } = await response.json();
console.log(workers, pagination.cursor);

export {};

Authentication

Send your namespace token as a bearer token in the Authorization header. Every control plane request also requires the namespace query parameter. See Authentication.

Query Parameters

Name	Type	Required	Description
`namespace`	`string`	Yes	Name of the namespace to operate in.
`name`	`string`	No	Only return workers with this name.
`envoy_key`	`string[]`	No	Only return workers with these keys. Repeat the parameter for multiple keys.
`limit`	`integer`	No	Maximum number of results to return.
`cursor`	`string`	No	Pagination cursor. Pass the `pagination.cursor` value from the previous response to fetch the next page.

Responses

200

Matching workers and a cursor for the next page.

Field	Type	Description
`envoys`	`object[]`
`envoys[].create_ts`	`integer`
`envoys[].datacenter`	`string`
`envoys[].envoy_key`	`string`
`envoys[].last_connected_ts`	`integer \| null`
`envoys[].last_ping_ts`	`integer`
`envoys[].last_rtt`	`integer`
`envoys[].metadata`	`object \| null`
`envoys[].namespace_id`	`string`
`envoys[].pool_name`	`string`
`envoys[].slots`	`integer`
`envoys[].stop_ts`	`integer \| null`
`envoys[].version`	`integer`
`pagination`	`object`
`pagination.cursor`	`string \| null`	Cursor for the next page, or `null` when there are no more results.

{
  "envoys": [
    {
      "create_ts": 1700000000000,
      "datacenter": "us-east",
      "envoy_key": "<envoy_key>",
      "last_connected_ts": null,
      "last_ping_ts": 1700000000000,
      "last_rtt": 0,
      "metadata": null,
      "namespace_id": "00000000-0000-0000-0000-000000000000",
      "pool_name": "<pool_name>",
      "slots": 0,
      "stop_ts": null,
      "version": 0
    }
  ],
  "pagination": {
    "cursor": null
  }
}