sessions module route (requires sessions:run:read)

GET

/v1/m/sessions/runs

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

• this engine

Lists the session runs newest first, optionally narrowed by state or by the provider session a run drives.

Authorizations

• bearerAuth
• browserSession

Parameters

Header Parameters

X-Olivares-Tenant

string format: uuid

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

Query Parameters

pagination

string

Allowed values: cursor

Optional cursor mode traverses every row in stable ID order; absent keeps the recency-ordered page and ignores cursor.

limit

integer

>= 1 <= 1000

Page size; default and maximum follow the store’s list contract. Without pagination=cursor, the caller’s own pinned sessions outside the page are added to it, at most 20 more rows; a list narrowed by state or provider_profile_ref answers the narrowed page alone.

cursor

string

Opaque cursor returned by the previous page; used only with pagination=cursor.

Responses

200

A page of runs, each with the six facts a console shows about a session

Media type application/json

object

cursor

Present in cursor mode when more rows follow.

string

has_more

required

boolean

items

required

Array<object>

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

key

additional properties

any

Example

{
  "items": [
    {
      "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

{}