List sessions

Cursor-paginated list of sessions on this host, filterable by repository, environment and status. One query across every repository.

GET /v1/sessions

List sessions

cURL

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

200

{
  "items": [
    {
      "id": "6b9f6d2e-1c3a-4f5b-9d7e-2a8c4e6f0b1d",
      "repository": "/Users/dev/repos/midaz",
      "status": "running",
      "clientKind": "inline",
      "createdAt": "2026-08-08T12:00:00.000Z",
      "updatedAt": "2026-08-08T12:34:56.000Z"
    }
  ],
  "limit": 25,
  "nextCursor": "b3BhcXVlLWN1cnNvcg",
  "spend": {
    "filtered": {
      "inputTokens": 41200000,
      "outputTokens": 1830000,
      "costUsd": 301.22
    },
    "page": {
      "inputTokens": 980000,
      "outputTokens": 44000,
      "costUsd": 7.15
    }
  }
}

Authorizations

Authorization · string · header · required

Enforced on every transport, with no exempt operation. A person's request — over the default local unix socket exactly as over a TCP listener — must carry a JWT issued by the configured identity provider, which the host verifies itself against that issuer's key set: signature, issuer, expiry, and the person and organisation it names. Requests without a valid one receive 401 NRY-0011. The socket's file permissions are transport and are not an authorisation.

Query Parameters

cursor · string

Opaque pagination cursor from a previous page's nextCursor or prevCursor.

Maximum string length: 1024

limit · integer · default: 25

Maximum items per page.

Required range: 1 <= x <= 100

repository · string

Filter to sessions bound to this repository path; on a hosted home, relative to its workspace, as each session names it.

Maximum string length: 4096

environment · string

Filter to sessions bound to this environment. Sessions running on the host's own machine are bound to none and match no value of this filter; omit it to see them. An environment's identifier, chosen by whoever creates it and unique on this host. It travels as one path segment, so its shape is bounded to what a path segment carries unchanged, exactly as a monitor's name is: a "/" would address no route and a "?" or "#" would end the segment early and address something else. One beginning conversation- is a hosted home's own, and a create naming it is 422.

Required string length: 1 - 64

Pattern: ^[A-Za-z0-9][A-Za-z0-9._-]*$

status · enum<string>

Filter by session status.

Available options: idle, running, waiting, archived

search · string

Filter to sessions whose title contains this text, matched case-insensitively. It exists so a client can reach a session by name past whatever prefix of the list it has read: a picker that filters the newest few hundred rows it holds cannot find a conversation from three months ago, and only the host can. Combines with the other filters.

Maximum string length: 512

mine · boolean

Restrict the listing to the conversations the caller owns. It names nobody and takes no name: the subject comes from the verified token and from nowhere else, which is what keeps it from being the owner parameter this contract deliberately does not have — an owner a caller can name is an owner anybody can be. It is not a permission and can only ever narrow. Spelled the same way, and meaning the same thing, as the mine on searchRecords and listRecordFiles. Combines with every other filter here.

Response

200

application/json

One page of sessions.

One page of sessions.

items · object[] · required

Show child attributes

limit · integer · required

Required range: x >= 1

nextCursor · string

Cursor for the next page; absent on the last page.

prevCursor · string

Cursor for the previous page; absent on the first page.

spend · object

What this listing costs, so a client drawing a fleet does not have to sum the rows it happens to have paged — a figure that grows as the reader scrolls and is wrong on every page but the last. It is not a second ledger. Every figure here sums the same model rounds the consumption report sums, at the same prices, over the conversations this request's filters name; where the two surfaces could disagree this one defers, because two spend screens that drift is a product people stop trusting. They answer an UNPRICED set differently, and deliberately: the report serves a floor with costComplete: false and the count beside it, while this envelope serves no costUsd at all with the count instead — because the rows in this same body have been all-or-nothing since they existed, and a footer reporting a floor over rows reporting absence would not equal the sum of the rows above it. THE WHOLE ENVELOPE IS ABSENT WHEN THE REQUEST CARRIES search, repository OR environment, and never partially present. Those three narrow by a name a person chose — a conversation's title, its working directory, and an environment identifier whoever created it invented, which listEnvironments serves to its owner alone — while these figures count the conversations somebody marked private under no permission at all. Served together they would answer what the read rule refuses: search=Longbow costing eleven dollars where search=Longbox costs nothing reads a private title one request at a time, environment=acme-acquisition reads a name the same way, and repository and environment both attribute that money to a named resource. Under those three the absence follows the FILTER and never what it matched, so it signals nothing itself — every such request is answered without an envelope, whether it matched a private conversation, a readable one or nothing. Spend grouped by repository lives on the consumption report, which is the operation built for it and which puts a private conversation's money in one opaque group rather than under a name. status and mine are not content and keep the envelope: a run's state is not something a person wrote, and mine narrows to the reader's own work. Separately, and for a different reason, a ledger this host cannot sum is answered with the rows and no envelope. That is one bit, the same under every filter and for every caller, and it names nothing.

Show child attributes