---
title: "List a project's shares"
method: GET
path: "/projects/{projectId}/shares"
tags: ["Projects"]
---

# List a project's shares

`GET /projects/{projectId}/shares`

## Request

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

Lists everyone the project is shared with individually, registered recipients and pending invitations alike, each at the role they actually hold. Owner-only.

`shares` lists individual shares only. `organization` is set when the project is also shared with an entire organization, which is done in the Elicit web interface; every active member of that organization holds the role it reports, and those members are **not** listed in `shares` unless they also hold an individual share of their own. A member who holds both is listed once, at the stronger of the two. `organization` is `null` when no organization currently reaches the project — including when a share exists but that organization's plan no longer includes sharing, since its members have no access.

### Example

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

## Path parameters

- `projectId` string, uuid, required: The project ID (UUID) from `GET /projects` or `POST /projects`

## Response `200`

The project's current shares.

- ListProjectSharesResponse
  - `projectId` string, uuid, required: The project ID (UUID) from `GET /projects` or `POST /projects`
  - `shares` ProjectShare[], required: Everyone the project is shared with individually — both registered recipients and pending email invitations. Members of an organization-wide share are not listed here unless they also hold an individual share; that access is reported in `organization` instead.
    - `email` string, required: Email address the project is shared with.
    - `status` 'registered' | 'invited', required: "registered" when the recipient already has an Elicit account and can read the project now; "invited" when a pending invitation was created for an email without an account.
    - `role` 'reader' | 'writer', required: The recipient's effective access level — the strongest of their own share and any organization-wide share that currently reaches them. This endpoint creates `reader` shares; `writer` means edit access was granted in the Elicit web interface.
  - `organization` object, nullable, required: The organization every one of whose active members can currently reach this project, or null if none can. Set in the Elicit web interface. An organization-wide share only grants access while that organization's plan includes sharing, so a share whose plan has lapsed reports null here — matching what the access checks actually allow.
    - `name` string, required
    - `memberCount` integer, required: Active members of the organization the project is shared with.
    - `role` 'reader' | 'writer', required: The access level every member of that organization has.
  - `url` string, required: URL to open this project in the Elicit web interface.

## Other responses

- `400`: A malformed id, or an unknown or invalid query parameter or body key.
- `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 project does not exist, or is not visible to you at the access this call needs.
- `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-13** `27c80b9a3470`: 5 info
  - added the optional property `error/details` to the response with the `400` status
  - added the optional property `error/details` to the response with the `401` status
  - added the optional property `error/details` to the response with the `403` status
  - added the optional property `error/details` to the response with the `404` status
  - …1 more
- **2026-09-27** `9b5b75b828ab`: 5 info
  - added the optional property `error/sessionId` to the response with the `400` status
  - added the optional property `error/sessionId` to the response with the `401` status
  - added the optional property `error/sessionId` to the response with the `403` status
  - added the optional property `error/sessionId` to the response with the `404` status
  - …1 more
- **2026-09-24** `282a68222364`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/elicit/apis/elicit-api/changes/projects/:projectId/shares/get.md)

---

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