Inspector

Get Queue

List pending queue messages and queue capacity details.

The inspector API is subject to change without notice. Do not build production integrations on it.

GET https://rivet.example.com/gateway/{actor}/inspector/queue

Examples

curl "https://rivet.example.com/gateway/$ACTOR_ID/inspector/queue?limit=50" \
  -H "Authorization: Bearer $INSPECTOR_TOKEN"

const endpoint = "https://api.rivet.dev";
const response = await fetch(
	`${endpoint}/gateway/${process.env.ACTOR_ID}/inspector/queue?limit=50`,
	{ headers: { Authorization: `Bearer ${process.env.INSPECTOR_TOKEN}` } },
);
console.log(await response.json());
export {};

Authentication

Inspector endpoints do not accept namespace tokens. Send the actor’s inspector token as a bearer token in the Authorization header.

Path Parameters

Name	Type	Required	Description
`actor`	`string`	Yes	Actor ID, actor ID with an inline token (`{actor_id}@{token}`), or actor name combined with the `rvt-*` query parameters.

Query Parameters

Name	Type	Required	Description
`limit`	`integer`	No	Maximum number of queue messages to return

Headers

Name	Type	Required	Description
`Authorization`	`string`	No	Bearer token for inspector authentication. Required in production, optional in development.

{actor} accepts an actor ID, an actor ID with an inline routing token ({actor_id}@{token}), or an actor name combined with the rvt-* query parameters below. See Actor Routing for the full rules.

Name	Type	Required	Description
`rvt-namespace`	`string`	No	Namespace the actor lives in. Required when `{actor}` is an actor name.
`rvt-method`	`string`	No	How to resolve an actor name to an actor. `getOrCreate` requires `rvt-pool`. One of `"get"`, `"getOrCreate"`.
`rvt-key`	`string`	No	Actor key. Separate multi-part keys with commas.
`rvt-pool`	`string`	No	Pool to create the actor on when `rvt-method=getOrCreate`. RivetKit registers the `default` pool unless configured otherwise.
`rvt-runner`	`string`	No	Deprecated alias for `rvt-pool`.
`rvt-input`	`string`	No	Base64url-encoded CBOR input passed to `createState` and `onCreate` when `rvt-method=getOrCreate` creates the actor.
`rvt-region`	`string`	No	Preferred region when `rvt-method=getOrCreate` creates the actor.
`rvt-crash-policy`	`string`	No	Crash policy when `rvt-method=getOrCreate` creates the actor. RivetKit defaults to `sleep`. One of `"restart"`, `"sleep"`, `"destroy"`.
`rvt-skip-ready-wait`	`boolean`	No	Return as soon as the actor is resolved instead of waiting for it to be ready.
`rvt-token`	`string`	No	Token to authenticate with. Prefer the `x-rivet-token` header or inline path token when possible.

Responses

200

Queue size, capacity, truncation status, and pending message metadata.

Field	Type	Description
`size`	`integer`
`maxSize`	`integer`
`truncated`	`boolean`
`messages`	`object[]`
`messages[].id`	`string`
`messages[].name`	`string`
`messages[].createdAtMs`	`integer`

{
  "size": 0,
  "maxSize": 0,
  "truncated": false,
  "messages": [
    {
      "id": "<id>",
      "name": "my-actor",
      "createdAtMs": 0
    }
  ]
}

401

The inspector token is missing or invalid.