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

# List sessions

`GET /sessions`

## Request

- Base URL: `https://elicit.com/api/v2`
- URL: `https://elicit.com/api/v2/sessions`
- Auth: HTTP bearer

List all sessions — reports, systematic reviews, and research-agent sessions — for the authenticated user in a single feed, ordered by creation date (newest first).

Each item carries its `sessionId`, a `type` field (`report`, `systematicReview`, or `agent`), and a `links` object with the URLs for the item's follow-up requests: `links.self` is the typed get endpoint for its full status and results, and `links.resume` appears only while the session is paused for insufficient quota. Agent items omit `executionStage` (agent sessions have no pipeline stages); for them `status: "completed"` means idle and awaiting input rather than terminally finished.

Results are paginated using cursor-based pagination. Use the `nextCursor` value from the response to fetch the next page. Filters apply to all session types; pass `type` to list a single kind.

### Example

```bash
# First page
curl https://elicit.com/api/v2/sessions?limit=10 \
  -H "Authorization: Bearer elk_live_your_key_here"

# Next page
curl "https://elicit.com/api/v2/sessions?limit=10&cursor=2025-06-15T14:30:00.000Z_5ad08bfb-cbe0-4911-a8c3-309760d33029" \
  -H "Authorization: Bearer elk_live_your_key_here"

# Only reports created via the API
curl "https://elicit.com/api/v2/sessions?type=report&source=api" \
  -H "Authorization: Bearer elk_live_your_key_here"
```

## Query parameters

- `limit` integer: Maximum number of sessions to return (default: 50, max: 100)
- `cursor` string: Opaque pagination cursor from a previous response's nextCursor field. Omit for the first page.
- `source` 'user' | 'api' | 'mcp' | 'agent_session': Filter by how the session was created
- `type` 'report' | 'systematicReview' | 'agent': Filter to a single session type
- `status` 'processing' | 'pausedForInsufficientQuota' | 'completed' | 'failed' | 'unknown': Filter by session status

## Response `200`

List of sessions.

- ListSessionsResponse
  - `sessions` SessionListItem[], required: Reports, systematic reviews, and research-agent sessions interleaved, ordered by creation date (newest first)
    - `type` 'report' | 'systematicReview' | 'agent', required: Which kind of session this is; use it to pick the matching typed get endpoint
    - `sessionId` string, uuid, required: The session ID (UUID) returned by the create endpoints and `GET /sessions`
    - `status` 'processing' | 'pausedForInsufficientQuota' | 'completed' | 'failed' | 'unknown', required: Current status of the report
    - `executionStage` 'gathering_sources' | 'screening_abstract' | 'screening_fulltext' | 'extracting_data' | 'generating_report' | 'done' | 'null', nullable: Current pipeline stage, or null when not yet known. Omitted entirely for agent sessions, which have no pipeline stages.
    - `title` string, required: Report title (the research question)
    - `url` string, required: URL to view the report in the Elicit web interface
    - `source` 'user' | 'api' | 'mcp' | 'agent_session', required: How the report was created
    - `createdAt` string, required: ISO 8601 timestamp of when the report was created
    - `isPublic` boolean, required: Whether the report is publicly accessible via its URL without authentication
    - `role` 'owner' | 'shared': The caller's relationship to this session: "owner" for a session the caller created, or "shared" for an agent session another user shared with them read-only. Reports and systematic reviews are always "owner".
    - `links` SessionLinks, required
      - `self` string, required: API URL for this session's full status and results (the typed get endpoint for its type)
      - `resume` string: API URL to resume this session. Present only while the session is paused for insufficient quota. Only the owner can use it; a shared recipient receives 404 even when this link is present.
  - `nextCursor` string, nullable, required: Opaque cursor for the next page; pass it back as `cursor`. Null if there are no more results.
  - `totalCount` integer, required: Total sessions matching the filters across all pages.

## Other responses

- `400`: The request body, query parameters, or path ID failed validation.
- `401`: Authentication failed.
- `403`: API access is not available on your current plan. Upgrade to Pro or above to use the API.
- `429`: Rate limit exceeded. More than 100 requests per minute were received from your IP address; further requests are blocked for 5 minutes.
- `500`: An unexpected error occurred. Retry reads with backoff; before retrying a write, check whether it took effect. See Error Handling for retry guidance.

## Changes

- **2026-10-16** `22847bf7e65d`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/elicitlabs/apis/elicit-labs-api/changes/sessions/get.md)

---

[API](https://skmtc.dev/elicitlabs/apis/elicit-labs-api.md) - [All operations](https://skmtc.dev/elicitlabs/apis/elicit-labs-api/llms.txt) - [OpenAPI document](https://skmtc.dev/elicitlabs/apis/elicit-labs-api/revisions/cbbe29509d04?raw)