Inspector

Get Traces

Get actor trace spans in OTLP JSON format.

The inspector API powers the Rivet dashboard and is subject to change without notice. Do not build production integrations on it.

Trace collection is not implemented yet, so this route currently returns an empty result.

GET https://api.rivet.dev/gateway/{actor}/inspector/traces

Examples

curl "https://api.rivet.dev/gateway/$ACTOR_ID/inspector/traces?startMs=0&limit=100" \
  -H "Authorization: Bearer $INSPECTOR_TOKEN"

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

Inspector endpoints do not accept namespace tokens. Send the actor’s inspector token as a bearer token in the Authorization header. Each actor generates its own inspector token on first start and stores it in its KV storage under the single byte 0x03. Read it through the control plane with GET /actors/{actor_id}/kv/keys/Aw==?namespace={namespace} using a namespace token; the response value is the token, base64-encoded. The dashboard does this for you.

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
`startMs`	`integer`	No	Start of time range in epoch milliseconds
`endMs`	`integer`	No	End of time range in epoch milliseconds. Defaults to now.
`limit`	`integer`	No	Maximum number of spans to return

Headers

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

Actor Selector

{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

Trace data and whether the requested range was clamped.

Field	Type	Description
`otlp`	`object`
`clamped`	`boolean`

{
  "otlp": {},
  "clamped": false
}

401

The inspector token is missing or invalid.