---
title: "List file shares"
method: GET
path: "/file/{id}/share"
tags: ["Files"]
---

# List file shares

`GET /file/{id}/share`

## Request

- Base URL: `https://api.elaichi.ai`
- URL: `https://api.elaichi.ai/file/{id}/share`
- Auth: HTTP bearer

Lists who a file is shared with, cursor-paginated. This is the only place the grant list is served — a file can be shared organization-wide, so no row embeds it (`access_summary` on `GET /file` is the bounded rollup). Filter with `grantee_type`; `q` matches member names and emails and team names. Owner only: ownership is the gate, and there is no `file:share` permission. A caller who is not the owner gets `403` ("Only the owner…") whenever the file is visible to them in `GET /file` (an explicit share, or `use` on its source connection or toolbox, restricted or not), because they already know it exists; `404` otherwise, including a listed row whose access through a connection or toolbox has broken (`can_open: false` for a lapsed toolbox delegation or a deleted connection).

## Path parameters

- `id` string, required

## Query parameters

- `limit` integer
- `cursor` string
- `q` string
- `grantee_type` 'user' | 'team' | 'org'

## Headers

- `X-Organization-Id` string

## Response `200`

OK

- object
  - `result` object[], required
    - `id` string: Share id (`acl_…`), the `{aclId}` that `DELETE …/share/{aclId}` takes.
    - `grantee_type` 'user' | 'team' | 'org'
    - `grantee_id` string, nullable: Null for org-wide grants.
    - `level` 'view': A file grants exactly one level.
    - `grantee` object: Resolved display data, so a page of grants needs no follow-up lookups.
      - `name` string, nullable
      - `email` string, nullable
      - `avatar_url` string, nullable: The person's picture: their stored profile picture, else a Gravatar URL (`d=404`, 96px) derived from their email (the address itself is not sent), else null. Draw initials when it is null or the image fails to load.
      - `member_count` integer, nullable: Team grants only: how many people the grant reaches.
    - `created_at` string, date-time
  - `next_cursor` string, nullable, required
  - `prev_cursor` string, nullable, required

## Other responses

- `400`: Bad request
- `401`: Unauthorized
- `403`: Forbidden
- `404`: Not found
- `429`: Rate limited

---

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