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://api.rivet.dev/actors

Examples

curl "https://api.rivet.dev/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`	Yes	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[].connectable_ts`	`integer \| null`	Denotes when the actor was last connectable. Null if actor is not running.
`actors[].crash_policy`	`"restart" \| "sleep" \| "destroy"`	What happens when the actor crashes.
`actors[].create_ts`	`integer`	Denotes when the actor was first created.
`actors[].datacenter`	`string`	Datacenter the actor is scheduled in.
`actors[].destroy_ts`	`integer \| null`	Denotes when the actor was destroyed.
`actors[].error`	`object \| null`	Error details if the actor failed to start.
`actors[].key`	`string \| null`	Actor key. Multi-part keys are joined with `/`, see Actor Keys.
`actors[].name`	`string`	Actor name as registered in your RivetKit registry.
`actors[].namespace_id`	`string`	ID of the namespace the actor belongs to.
`actors[].pending_allocation_ts`	`integer \| null`	Denotes when the actor started waiting for an allocation.
`actors[].reschedule_ts`	`integer \| null`	Denotes when the actor will try to allocate again. If this is set, the actor will not attempt to allocate until the given timestamp.
`actors[].runner_name_selector`	`string`	Pool the actor runs on.
`actors[].sleep_ts`	`integer \| null`	Denotes when the actor entered a sleeping state.
`actors[].start_ts`	`integer \| null`	Denotes when the actor was first made connectable. Null if never.
`pagination`	`object`
`pagination.cursor`	`string \| null`	Cursor for the next page, or `null` when there are no more results.

{
  "actors": [
    {
      "actor_id": "00000000-0000-0000-0000-000000000000",
      "connectable_ts": null,
      "crash_policy": "restart",
      "create_ts": 1700000000000,
      "datacenter": "us-east",
      "destroy_ts": null,
      "error": null,
      "key": null,
      "name": "my-actor",
      "namespace_id": "00000000-0000-0000-0000-000000000000",
      "pending_allocation_ts": null,
      "reschedule_ts": null,
      "runner_name_selector": "default",
      "sleep_ts": null,
      "start_ts": null
    }
  ],
  "pagination": {
    "cursor": null
  }
}