---
title: "List a session's shares"
method: GET
path: "/sessions/{sessionId}/shares"
tags: ["Sessions"]
---

# List a session's shares

`GET /sessions/{sessionId}/shares`

## Request

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

List everyone a session is shared with **read-only** — both registered recipients and pending email invitations. Reports and systematic reviews can also have editors or reviewers added in the Elicit web app; those higher-permission collaborators are not returned here. This list is not a complete permission inventory: DELETE by email can revoke those unlisted higher-permission shares too. Only the session owner can list shares.

### Example

```bash
curl https://elicit.com/api/v2/sessions/{sessionId}/shares \
  -H "Authorization: Bearer elk_live_your_key_here"
```

## Path parameters

- `sessionId` string, uuid, required: The session ID (UUID) returned by the create endpoints and `GET /sessions`

## Response `200`

The session's current read-only shares.

- ListSessionSharesResponse
  - `sessionId` string, required: Unique identifier for the session.
  - `shares` SessionShare[], required: Read-only recipients and pending read-only invitations. Existing editors and reviewers are not listed; manage those collaborators in the web interface.
    - `email` string, required: Email address the session is shared with.
    - `status` 'registered' | 'invited', required: "registered" when the recipient already has an Elicit account and can read the session now; "invited" when a pending invitation was created for an email without an account.
    - `role` 'reader', required: Read-only access requested through this API. Creating a share preserves any existing editor/reviewer permissions, so this field is not a complete description of effective access.
  - `url` string, required: URL to view the session in the Elicit web interface. Available actions depend on your permissions.

## Other responses

- `400`: The request body, query parameters, or path ID failed validation.
- `401`: Authentication failed. The API key is missing, invalid, revoked, or expired.
- `403`: API access is not available on your current plan. Upgrade to Pro or above to use the API.
- `404`: The session does not exist or is not accessible to you for this operation.
- `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/:sessionId/shares/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)