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

# List sessions

`GET /sessions`

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: 20, 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.
  - `nextCursor` string, nullable, required — Opaque cursor for the next page; pass it back as `cursor`. Null if there are no more results.

## Other responses

- `401` — Authentication failed.
- `403` — API access is not available on your current plan. Upgrade to Pro or above to use the API.

---

[API](https://skmtc.dev/elicit/apis/elicit-api.md) · [All operations](https://skmtc.dev/elicit/apis/elicit-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/elicit/elicit-api/revisions/2b42624536e5/schema)