sessions module route (requires sessions:run:read)

GET

/v1/m/sessions/runs/{ref}

curl --request GET \
  --url https://example.com/v1/m/sessions/runs/example \
  --header 'Authorization: Bearer <token>'

• this engine

Returns one session run by reference.

Authorizations

• bearerAuth
• browserSession

Parameters

Path Parameters

ref

required

string

Path parameter ref.

Header Parameters

X-Olivares-Tenant

string format: uuid

Target tenant id; required when the principal can act in more than one tenant.

Responses

200

The run, with the six facts a console shows about a session

Media type application/json

object

acts_for

object

kind

required

A person launched it, a work item or agent dispatched it, or the session predates the launcher record.

string

Allowed values: user automation unknown

name

The account’s display name.

string

reason

Why a value is null or missing; present only then.

string

user_id

The account that launched the session.

string

approvals

object

approved

required

Any of:

integer

Actions of this session a person approved; null when no approval source could be read.

integer format: int64

null

null

reason

Why a value is null or missing; present only then.

string

waiting

required

Actions of this session waiting for a person now.

integer format: int64

cost

object

limit_micro_usd

The limit, in micro-USD, of the most restrictive budget scoped to this session or to its agent identity; present only when one applies.

integer format: int64

limit_period

The period that budget counts over.

string

Allowed values: daily weekly monthly total

micro_usd

required

Any of:

integer

Cost so far in micro-USD, from the tokens the tool reported at list price. Null, never 0, when the tool reported nothing to price.

integer format: int64

null

null

reason

Why a value is null or missing; present only then.

string

proof

object

chain_verified

required

Any of:

boolean

Whether the tenant’s audit hash chain verifies up to its newest entry; null when the ledger could not be read or holds no entry. Each entry is checked when the engine first reads it; olivares audit verify re-walks the whole chain.

boolean

null

null

ledger_entries

required

Any of:

integer

Audit ledger entries that record this session: they target it, name its run or session in their metadata, or its session identity wrote them.

integer format: int64

null

null

reason

Why a value is null or missing; present only then.

string

reaches

object

folders

required

The session folder and the read-only folders of its workspace.

Array<object>

object

access

required

Unknown when the folder’s workspace could not be read or no longer exists.

string

Allowed values: write read unknown

path

required

A folder on the engine host.

string

hosts

required

Hosts the session may connect to besides the engine: the bound provider’s endpoint, then the profile’s declared hosts.

Array<string>

reason

Why a value is null or missing; present only then.

string

run_ref

required

The operated session’s stable reference.

string

runs_as

object

account

The provider account name of that profile.

string

label

required

Tool and account, ready to show: Claude Code · team-a.

string

profile_ref

The provider profile the session runs under.

string

reason

Why no account is shown: the session runs without a provider profile, or its profile could not be read or no longer exists.

string

tool

required

The session driver key, e.g. claude.

string

tool_name

The tool’s display name, e.g. Claude Code.

string

state

required

The run’s derived lifecycle state.

string

key

additional properties

any

Example

{
  "acts_for": {
    "kind": "user"
  },
  "cost": {
    "limit_period": "daily"
  },
  "reaches": {
    "folders": [
      {
        "access": "write"
      }
    ]
  }
}

400

Bad request

Media type application/json

object

Example ^generated

{}

401

Unauthenticated

Media type application/json

object

Example ^generated

{}

403

Forbidden

Media type application/json

object

Example ^generated

{}

404

Not found

Media type application/json

object

Example ^generated

{}

409

Conflict / setup required

Media type application/json

object

Example ^generated

{}

429

Rate limited

Media type application/json

object

Example ^generated

{}