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

# List sessions

`GET /sessions`

## Request

- Base URL: `https://api.parley.so/v1`
- URL: `https://api.parley.so/v1/sessions`
- Auth: HTTP bearer

List your sessions with Parley's assistant, most recently active first by default, from every place you work with it: the web app, Word, Outlook, automation runs, and the API. Other people's sessions aren't listed.

## Query parameters

- `search` string: Case-insensitive. Only sessions whose title contains this text.
- `status` 'working' | 'idle': Only sessions that are working, or only idle ones.
- `origin` 'web' | 'word' | 'outlook' | 'automation' | 'api': Only sessions started from here.
- `projectId` string: Only sessions that work in this project.
- `automationId` string: Only sessions this automation's runs started.
- `createdSince` string: Only records created at or after this time. An ISO 8601 date (YYYY-MM-DD, read as UTC midnight) or date-time.
- `createdBefore` string: Only records created before this time. An ISO 8601 date (YYYY-MM-DD, read as UTC midnight) or date-time.
- `updatedSince` string: Only records last updated at or after this time. An ISO 8601 date (YYYY-MM-DD, read as UTC midnight) or date-time.
- `updatedBefore` string: Only records last updated before this time. An ISO 8601 date (YYYY-MM-DD, read as UTC midnight) or date-time.
- `sort` 'createdAt' | '-createdAt' | 'updatedAt' | '-updatedAt': Sort order: a field name, prefixed with - for descending. Defaults to -updatedAt.
- `cursor` string: Opaque cursor from nextCursor. Pass the same filters and sort. Omit for the first page.
- `limit` integer: Maximum number of items to return.

## Response `200`

OK

- object
  - `data` object[], required
    - `id` string, required: The session ID.
    - `title` string, nullable, required: The session's title, written by Parley after the first reply unless someone named it, or null until then.
    - `status` 'working' | 'idle', required: working: Parley's assistant is working, a message is waiting for it, or it is waiting on subagents it started in the background. idle: the assistant has stopped and is waiting for the next message.
    - `origin` 'web' | 'word' | 'outlook' | 'automation' | 'api', required: Where the session was started: web (Parley's web app, or an email to Parley's assistant), word or outlook (the add-in), automation (an automation run), or api (the REST API, MCP, or the CLI).
    - `project` ProjectRef, required: The project's type, ID, and name.
      - `type` 'project', required
      - `id` string, required: Its ID.
      - `name` string, required: The project name.
    - `automation` object, nullable, required: The automation's type, ID, and name.
      - `type` 'automation', required
      - `id` string, required: Its ID.
      - `name` string, required: The automation name.
    - `lastRun` object, nullable, required: The assistant's most recent pass over the session's messages, or null before it starts.
      - `status` 'running' | 'completed' | 'interrupted' | 'failed', required: running: in progress. completed: the assistant finished. interrupted: someone stopped it. failed: it ended with an error.
      - `startedAt` string, date-time, required: When the assistant started.
      - `endedAt` string, date-time, nullable, required: When the assistant stopped, or null while it is running.
      - `error` object, nullable, required: Why a failed run failed, or null.
        - `code` string, nullable, required: Machine-readable reason, such as CONTEXT_WINDOW_EXCEEDED, or null.
        - `message` string, required: Human-readable description.
    - `url` string, uri, required: Where to open the session in Parley.
    - `createdAt` string, date-time, required: When the session was started.
    - `updatedAt` string, date-time, required: When the session last changed, such as by a new message.
  - `nextCursor` string, nullable, required: Cursor for the next page, or null on the last page.

## Other responses

- `400`: The request was invalid. VALIDATION_FAILED, INVALID_CURSOR.
- `401`: Missing or invalid credentials. UNAUTHORIZED.
- `403`: You don't have permission. FORBIDDEN.
- `429`: Too many requests, or a usage limit was reached. TOO_MANY_REQUESTS.

---

[API](https://skmtc.dev/parley/apis/parley-api.md) - [All operations](https://skmtc.dev/parley/apis/parley-api/llms.txt) - [OpenAPI document](https://skmtc.dev/parley/apis/parley-api/revisions/6b78aeee07bc?raw)