Skip to content
WAMP Cloud

Page Sessions visible to the installation

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

Requires wamp.cloud.sessions:read. Ordered newest-updated first and paged by an opaque cursor: pass the previous page’s nextCursor back verbatim and stop when hasMore is false. Because the sort key is updatedAt, a Session that changes mid-walk can move between pages — treat this as a browse surface and use the per-Session event log when you need exactness. Archived Sessions are excluded, and only Sessions this installation created or was granted access to are visible; a hand-built or foreign cursor is a 400, not an empty page.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Query Parameters

Section titled “Query Parameters”
cursor
string
<= 1024 characters

Opaque exclusive cursor returned by the previous page

limit
integer
default: 50 >= 1 <= 100

Sessions per page, 1-100, default 50

Responses

Section titled “Responses”

200

Section titled “200”

Session page

Media typeapplication/json

One page of the Sessions this credential may see, ordered by updatedAt descending so active work sorts first. Archived Sessions are excluded.

object
sessions
required

Sessions on this page, most recently updated first

Array<object>

The durable unit of agent work: a Session owns its Turns, Runs, Events, Artifacts and Publications, and outlives any sandbox that happens to be executing it.

object
id
required

The caller-owned Session id, unchanged from the create request

string format: uuid
sessionUrl
required

Canonical first-party browser URL for handing this Session to a human

string format: uri
organizationId
required

Organization that owns the Session; every credential is authorized against this organization

string format: uuid
title
required

Human-facing name — the supplied title, or one derived from task when none was given

string
origin

Correlation metadata supplied at creation; absent when none was sent

object
tenantKey
required

Stable opaque identifier for the external tenant the work belongs to, not its display name

string
>= 1 characters <= 128 characters
objectType
required

The caller’s own kind name for the originating record, such as ticket or issue

string
>= 1 characters <= 64 characters
objectId
required

The caller’s stable opaque id for that record, so a Session can always be traced back to the business object

string
>= 1 characters <= 256 characters
endUserId

Stable one-way hash of the external tenant/user pair; never raw PII.

string
>= 1 characters <= 128 characters
label

Short human-readable name for the originating record, shown when the Session is handed to a person

string
<= 256 characters
url

HTTPS deep link back to the originating record in the caller’s product

string format: uri
/^https:///
source

Repository checked out into the sandbox, with the exact base the Session was pinned to; absent for a Session with no repository

object
One of:
object
kind
required
Allowed value: public
url
required
string
label
required
string
model

Model in effect for the next Turn; absent when a runtime-managed agent supplies its own default

string
runtime

The settled foreign agent runtime id, such as claude-code or codex; absent means the native WAMP runtime

string
workspace
required

Sandbox attachment — unavailable when no lease is held, attached with the lease expiresAt, expired once that lease has lapsed; losing it does not end the Session

object
state
required
string
Allowed values: unavailable attached expired
expiresAt
string format: date-time
continuation
required

Whether and at what fidelity this Session can be carried into another Run

object
canContinue
required

Whether a new Turn can be admitted for this Session; false only while state is unavailable

boolean
state
required

live while a sandbox lease is still held, fresh before any Run has been accepted, restorable when a sealed checkpoint can be replayed into a new sandbox, unavailable when neither is possible

string
Allowed values: live fresh restorable unavailable
conversation
required

Fidelity the conversation would be restored at — live in an attached sandbox, exact from a full checkpoint, result_only when just prior results survive, none when nothing does

object
fidelity
required
string
Allowed values: live exact result_only none
workspace
required

Fidelity the working tree would be restored at — live, portable_tree from a checkpointed tree, or none

object
fidelity
required
string
Allowed values: live portable_tree none
environment
required

Always current: a restore lands in the currently promoted execution environment, and Cloud never claims it retained a specific image or runtime digest

object
fidelity
required
Allowed value: current
boundaryRunId

The Run whose completion sealed the checkpoint this projection describes; absent when no checkpoint exists

string format: uuid
reason

Why continuation is impossible — checkpoint_unavailable, conversation_not_restorable, or workspace_not_restorable; present only when canContinue is false

string
phase
required

Last execution phase the runner reported (idle, provisioning, running, awaiting, finalizing, completed, failed); advisory presentation state — read the Run for authoritative status

string
createdBy
required

Whether a human user or an App installation created the Session, and that actor’s id; an installation-created Session keeps its App authority even when a human later manages it

object
kind
required
string
Allowed values: user app_installation
id
required

A UUID identifying one Cloud resource; Session, Turn, Publication and Merge ids are minted by the caller so an ambiguous retry addresses the same durable command instead of creating a second one.

string format: uuid
activeRun

Present only while a Run is queued, dispatching or running — this is the id to cancel

object
id
required

A UUID identifying one Cloud resource; Session, Turn, Publication and Merge ids are minted by the caller so an ambiguous retry addresses the same durable command instead of creating a second one.

string format: uuid
createdAt
required

When the Session was admitted

string format: date-time
updatedAt
required

Last time durable Session state changed; the Session list is ordered by this value descending

string format: date-time
nextCursor
required

Opaque exclusive keyset cursor derived from the last item’s updatedAt and id; send it back unchanged as cursor and never parse or construct it yourself

string | null
hasMore
required

Whether more Sessions follow this page — stop paging on this flag, not on a null cursor

boolean
Example
{
  "sessions": [
    {
      "id": "9f2b7c14-59d3-4f7a-b8e1-2a6c05d4e731",
      "sessionUrl": "https://cloud.wamp.dev/sessions/9f2b7c14-59d3-4f7a-b8e1-2a6c05d4e731",
      "organizationId": "0b9a6f3e-5c21-4d78-9e64-8f1a2b7c3d05",
      "title": "Rate limit the payments endpoint",
      "origin": {
        "tenantKey": "acme",
        "objectType": "issue",
        "objectId": "PAY-4821",
        "endUserId": "9c1f0a7d4b62e35810af2d6c95b7e043",
        "label": "PAY-4821 Rate limit the payments endpoint",
        "url": "https://acme.example.com/issues/PAY-4821"
      },
      "source": {
        "kind": "github",
        "grantId": "74c5a903-8e6f-4b1d-a052-3c9e18d7f64b",
        "label": "acme/checkout-service",
        "private": true,
        "baseBranch": "main",
        "baseOid": "5a3e170c93eda8209e3f5592fe1e1d9976fe26ab"
      },
      "model": "claude-opus-5",
      "runtime": "wamp",
      "workspace": {
        "state": "attached",
        "expiresAt": "2026-08-12T11:40:00Z"
      },
      "continuation": {
        "canContinue": true,
        "state": "live",
        "conversation": {
          "fidelity": "live"
        },
        "workspace": {
          "fidelity": "live"
        },
        "environment": {
          "fidelity": "current"
        }
      },
      "phase": "running",
      "createdBy": {
        "kind": "app_installation",
        "id": "e3f7b219-6c40-4a8e-b591-07d2c48f3a65"
      },
      "activeRun": {
        "id": "c47a1e08-3d6b-4a92-9f15-8b70d2e5c6a4"
      },
      "createdAt": "2026-08-12T09:20:14Z",
      "updatedAt": "2026-08-12T09:41:02Z"
    },
    {
      "id": "4d81a6c2-90fb-4e37-8a15-c7be2f930d68",
      "sessionUrl": "https://cloud.wamp.dev/sessions/4d81a6c2-90fb-4e37-8a15-c7be2f930d68",
      "organizationId": "0b9a6f3e-5c21-4d78-9e64-8f1a2b7c3d05",
      "title": "Upgrade the checkout service to Node 22",
      "source": {
        "kind": "github",
        "grantId": "74c5a903-8e6f-4b1d-a052-3c9e18d7f64b",
        "label": "acme/checkout-service",
        "private": true,
        "baseBranch": "main",
        "baseOid": "4e6a86e45e9999efbe0c50ad3cc311ca9d214f61"
      },
      "model": "claude-opus-5",
      "runtime": "wamp",
      "workspace": {
        "state": "unavailable"
      },
      "continuation": {
        "canContinue": true,
        "state": "restorable",
        "conversation": {
          "fidelity": "exact"
        },
        "workspace": {
          "fidelity": "portable_tree"
        },
        "environment": {
          "fidelity": "current"
        },
        "boundaryRunId": "8f2d5b41-6e0c-47a9-b3d8-51ca9e07f2b6"
      },
      "phase": "idle",
      "createdBy": {
        "kind": "app_installation",
        "id": "e3f7b219-6c40-4a8e-b591-07d2c48f3a65"
      },
      "createdAt": "2026-08-11T16:02:47Z",
      "updatedAt": "2026-08-11T17:31:09Z"
    }
  ],
  "nextCursor": "eyJ2IjoxLCJraW5kIjoic2Vzc2lvbnMiLCJhdCI6IjIwMjYtMDgtMTFUMTc6MzE6MDkuMDAwWiIsImlkIjoiNGQ4MWE2YzItOTBmYi00ZTM3LThhMTUtYzdiZTJmOTMwZDY4In0",
  "hasMore": true
}

400

Section titled “400”

Malformed request

Media typeapplication/json

Failure body returned with every non-2xx JSON response; branch on the machine code, never on prose or on the HTTP status alone.

object
error
required

Stable machine code

string
requiredScope

The installation capability the presented credential lacks, returned with insufficient_scope so an integrator knows exactly which capability to request

string
retryAfterSeconds

Advisory seconds to wait before retrying; returned on rate-limit denials, where the Retry-After header carries the same value

integer
>= 1
key
additional properties
any
Example
{
  "error": "invalid_request"
}

401

Section titled “401”

Missing, expired or wrong-audience bearer

Media typeapplication/json

Failure body returned with every non-2xx JSON response; branch on the machine code, never on prose or on the HTTP status alone.

object
error
required

Stable machine code

string
requiredScope

The installation capability the presented credential lacks, returned with insufficient_scope so an integrator knows exactly which capability to request

string
retryAfterSeconds

Advisory seconds to wait before retrying; returned on rate-limit denials, where the Retry-After header carries the same value

integer
>= 1
key
additional properties
any
Example
{
  "error": "unauthorized"
}

403

Section titled “403”

Live installation, scope or organization policy denies the operation

Media typeapplication/json

Failure body returned with every non-2xx JSON response; branch on the machine code, never on prose or on the HTTP status alone.

object
error
required

Stable machine code

string
requiredScope

The installation capability the presented credential lacks, returned with insufficient_scope so an integrator knows exactly which capability to request

string
retryAfterSeconds

Advisory seconds to wait before retrying; returned on rate-limit denials, where the Retry-After header carries the same value

integer
>= 1
key
additional properties
any
Example
{
  "error": "insufficient_scope",
  "requiredScope": "wamp.cloud.sessions:create"
}