Manage Actors

List Actors

List actors in a namespace, optionally filtered by name, key, or ID. Results are paginated.

key requires name. actor_id cannot be combined with name or key. Destroyed actors are excluded unless include_destroyed is true.

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 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`	No	Name of the namespace to operate in.
`name`	`string`	No	Only return actors with this name.
`key`	`string`	No	Only return the actor with this key. Requires `name`. Multi-part keys are joined with `/`, see Actor Keys.
`actor_ids`	`string`	No	Deprecated. Use `actor_id` instead.
`actor_id`	`string`	No	Only return actors with these IDs. Repeat the parameter for multiple IDs.
`include_destroyed`	`boolean`	No	Include actors that have been destroyed.
`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 actors and a cursor for the next page. pagination.cursor is null on the last page.

Field	Type	Description
`actors`	`object[]`
`actors[].actor_id`	`string`	Unique ID of the actor.
`actors[].name`	`string`	Actor name as registered in your RivetKit registry.
`actors[].key`	`string`	Actor key. Multi-part keys are joined with `/`, see Actor Keys.
`actors[].namespace`	`string`	Name of the namespace the actor belongs to.
`actors[].pool`	`string`	Name of the node pool the actor runs in.
`actors[].create_ts`	`integer`	When the actor was created, in Unix milliseconds.
`actors[].start_ts`	`integer \| null`	When the actor first started. Not recorded by this version, so always `null`.
`actors[].pending_allocation_ts`	`integer \| null`	When the actor started waiting for a node. Not recorded by this version, so always `null`.
`actors[].connectable_ts`	`integer \| null`	When the actor last became connectable. Not recorded by this version, so always `null`.
`actors[].sleep_ts`	`integer \| null`	When the actor went to sleep. Not recorded by this version, so always `null`.
`actors[].reschedule_ts`	`integer \| null`	When the actor will next try to allocate. Not recorded by this version, so always `null`.
`actors[].destroy_ts`	`integer \| null`	When the actor was destroyed, in Unix milliseconds. Only set in listings that include destroyed actors; otherwise `null`.
`pagination`	`object`
`pagination.cursor`	`string \| null`	Cursor for the next page, or `null` when there are no more results.

{
  "actors": [
    {
      "actor_id": "d97pbq1nyqxw1w5qdwz0iirbqiblh2",
      "name": "my-actor",
      "key": "my-key",
      "namespace": "my-namespace",
      "pool": "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
  }
}

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.

Field	Type	Description
`group`	`string`	Error group, for example `actor`.
`code`	`string`	Error code within the group, for example `not_found`.
`message`	`string`	Human-readable error message.
`metadata`	`any`	Extra details. Only present on some errors raised while authenticating or authorizing the request.

{
  "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.

Field	Type	Description
`group`	`string`	Error group, for example `actor`.
`code`	`string`	Error code within the group, for example `not_found`.
`message`	`string`	Human-readable error message.
`metadata`	`any`	Extra details. Only present on some errors raised while authenticating or authorizing the request.

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

403

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

Field	Type	Description
`group`	`string`	Error group, for example `actor`.
`code`	`string`	Error code within the group, for example `not_found`.
`message`	`string`	Human-readable error message.
`metadata`	`any`	Extra details. Only present on some errors raised while authenticating or authorizing the request.

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

404

namespace.not_found: the namespace does not exist.

Field	Type	Description
`group`	`string`	Error group, for example `actor`.
`code`	`string`	Error code within the group, for example `not_found`.
`message`	`string`	Human-readable error message.
`metadata`	`any`	Extra details. Only present on some errors raised while authenticating or authorizing the request.

{
  "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.

Field	Type	Description
`group`	`string`	Error group, for example `actor`.
`code`	`string`	Error code within the group, for example `not_found`.
`message`	`string`	Human-readable error message.
`metadata`	`any`	Extra details. Only present on some errors raised while authenticating or authorizing the request.

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

503

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

Field	Type	Description
`group`	`string`	Error group, for example `actor`.
`code`	`string`	Error code within the group, for example `not_found`.
`message`	`string`	Human-readable error message.
`metadata`	`any`	Extra details. Only present on some errors raised while authenticating or authorizing 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."
}