---
title: "List sessions"
method: GET
path: "/api/session"
tags: ["session"]
---

# List sessions

`GET /api/session`

## Request

- Base URL: `https://opencode.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://opencode.ai/api/session`
- Auth: none required

Retrieve sessions in the requested order. Items keep that order across pages; use cursor.next or cursor.previous to move through the ordered list.

## Query parameters

- `limit` string, nullable: Maximum number of sessions to return. Defaults to the newest 50 sessions.
- `order` 'asc' | 'desc', nullable: Session order for the first page. Use desc for newest first or asc for oldest first.
- `search` string, nullable
- `parentID` union
  - string
  - 'null'
- `archived` 'true' | 'false', nullable
- `directory` string
- `project` string
- `subpath` string
- `cursor` string: Opaque pagination cursor returned as cursor.previous or cursor.next in the previous response.

## Response `200`

SessionsResponse

- SessionsResponse
  - `data` SessionInfo[], required
    - `id` string, required
    - `parentID` string
    - `fork` object
      - `sessionID` string, required
      - `boundary` union, required
        - object
          - `type` 'before', required
          - `messageID` string, required
        - object
          - `type` 'through', required
          - `messageID` string, required
    - `projectID` string, required
    - `agent` string
    - `model` ModelRef
      - `id` string, required
      - `providerID` string, required
      - `variant` string
    - `cost` number, required
    - `tokens` TokenUsageInfo, required
      - `input` number, required
      - `output` number, required
      - `reasoning` number, required
      - `cache` object, required
        - `read` number, required
        - `write` number, required
    - `outcome` 'succeeded' | 'failed' | 'interrupted'
    - `time` object, required
      - `created` number, required
      - `updated` number, required
      - `idle` number
      - `viewed` number
      - `archived` number
    - `title` string
    - `subpath` string
    - `metadata` SessionMetadata
    - `permissions` PermissionRule[]
      - `action` string, required
      - `resource` string, required
      - `effect` 'allow' | 'deny' | 'ask', required
    - `revert` SessionRevert
      - `messageID` string, required
      - `partID` string
      - `snapshot` string
      - `files` FileDiffInfo[]
        - `file` string, required
        - `patch` string, required
        - `additions` integer, required
        - `deletions` integer, required
        - `status` 'added' | 'deleted' | 'modified', required
        - `more` true
    - `location` LocationPublicRef, required
      - `directory` string, required
  - `cursor` object, required
    - `previous` string: Opaque pagination cursor returned as cursor.previous or cursor.next in the previous response.
    - `next` string: Opaque pagination cursor returned as cursor.previous or cursor.next in the previous response.

## Other responses

- `400`: InvalidCursorError | InvalidRequestError
- `401`: UnauthorizedError

## Changes

> 50 revisions in range; 1 not diffed.

- **2026-10-26** `aa0f65b3d158`: 1 info
  - added the optional property `data/items/revert/files/items/more` to the response with the `200` status
- **2026-10-24** `1c30ec162e7f`: 1 warning
  - removed the optional property `data/items/allowance` from the response with the `200` status
- **2026-10-24** `231ec98d2d97`: 1 info
  - added the optional property `data/items/allowance` to the response with the `200` status
- **2026-10-20** `7d8042ed3561`: 1 info
  - added the new optional `query` request parameter `archived`

[Operation history](https://skmtc.dev/kaaass/apis/opencode/changes/api/session/get.md)

---

[API](https://skmtc.dev/kaaass/apis/opencode.md) - [All operations](https://skmtc.dev/kaaass/apis/opencode/llms.txt) - [OpenAPI document](https://skmtc.dev/kaaass/apis/opencode/revisions/4e083d954707?raw)