Manage Actors

Get Actor

Get a live actor by ID.

Returns actor.not_found for an actor that was destroyed or belongs to another namespace. A namespace token needs a grant on actor with read.

GET https://rivet.example.com/actors/{actor_id}

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.

Path Parameters

Name	Type	Required	Description
`actor_id`	`string`	Yes	ID of the actor.

Query Parameters

Name	Type	Required	Description
`namespace`	`string`	No	Name of the namespace to operate in. Defaults to `default`.

Responses

200

The actor.

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

{
  "actor": {
    "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
  }
}

400

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": "envoy",
  "code": "invalid_namespace_name",
  "message": "Namespace name must be a DNS label of 1 to 63 lowercase letters, digits and hyphens."
}

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. For a namespace token this is also returned when the actor 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": "auth",
  "code": "insufficient_permissions",
  "message": "Insufficient permissions to access this resource."
}

404

actor.not_found: the actor does not exist, was destroyed, or belongs to another namespace. 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": "actor",
  "code": "not_found",
  "message": "The actor does not exist or was destroyed."
}

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