List Actors

List actors in a namespace by ID, by name and key, or by name. Listings by name are paginated.

Pass actor_ids (comma-separated) to look up actors by ID, or name with an optional key. actor_ids takes precedence over name and key. Only a listing by name without key is paginated; a page can hold fewer than limit actors while pagination.cursor is still set. Destroyed actors are excluded unless include_destroyed is true. A namespace token needs a grant on actor with list.

GET https://rivet.example.com/actors

Examples

curl "https://rivet.example.com/actors?namespace=$RIVET_NAMESPACE&name=counter" \
  -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, name: "counter" });
const response = await fetch(`${endpoint}/actors?${params}`, {
	headers: { Authorization: `Bearer ${token}` },
});

const { actors, pagination } = await response.json();
for (const actor of actors) {
	console.log(actor.actor_id, actor.name, actor.key);
}
// Pass pagination.cursor as ?cursor= to fetch the next page.
console.log(pagination.cursor);

export {};

Authentication

Send the admin token, or a namespace token from Create Token whose grants cover the request, as a bearer token in the Authorization header. The x-rivet-token header is also accepted. Routes with a namespace query parameter use the default namespace when it is omitted. See Authentication.

Query Parameters

Responses

200

Matching actors and a cursor for the next page. pagination.cursor is null on the last page.

{
  "actors": [
    {
      "actor_id": "d97pbq1nyqxw1w5qdwz0iirbqiblh2",
      "name": "my-actor",
      "key": "my-key",
      "namespace": "my-namespace",
      "runner_name_selector": "default",
      "create_ts": 1700000000000,
      "start_ts": null,
      "pending_allocation_ts": null,
      "connectable_ts": null,
      "sleep_ts": null,
      "reschedule_ts": null,
      "destroy_ts": null
    }
  ],
  "pagination": {
    "cursor": null
  }
}

400

actor.invalid_listing: neither name nor actor IDs were given. actor.invalid_include_destroyed, actor.invalid_limit, actor.invalid_cursor: the parameter is malformed. actor.invalid_key_encoding: key is not in canonical slash-separated form. envoy.invalid_namespace_name: the namespace value is not a DNS label of 1 to 63 lowercase letters, digits and hyphens.

{
  "group": "actor",
  "code": "invalid_listing",
  "message": "Listing actors requires a name or actor IDs."
}

401

auth.invalid_token: the request carries no token, or the token is not valid. auth.token_expired: the token has expired.

{
  "group": "auth",
  "code": "invalid_token",
  "message": "Authentication token is invalid."
}

403

auth.insufficient_permissions: the token’s grants do not cover this request.

{
  "group": "auth",
  "code": "insufficient_permissions",
  "message": "Insufficient permissions to access this resource."
}

404

namespace.not_found: the namespace does not exist.

{
  "group": "namespace",
  "code": "not_found",
  "message": "The namespace does not exist."
}

500

core.internal_error: an unexpected failure, including an actor ID that is not a valid Rivet ID.

{
  "group": "core",
  "code": "internal_error",
  "message": "An internal error occurred"
}

503

auth.verification_unavailable: token verification keys are temporarily unavailable. Retry the request.

{
  "group": "auth",
  "code": "verification_unavailable",
  "message": "The server could not verify the authentication token because verification keys are temporarily unavailable. Retry the request."
}