# List Share Links

- **Method:** `GET`
- **Path:** `/api/v1/runs/{run_id}/shares`
- **Operation ID:** `list_share_links`
- **Tags:** shares

Every public link minted on a run's sessions, newest first - live, expired and revoked - with who minted
each, when it expires and how often it was opened. Never a link itself: that was shown once, when it was
minted. `public_shares` says whether your tenant may share at all; while it is off no link plays.
`mask_required` says whether a session of yours is shared only when the browser pool recorded it under its
mask (the session row's `recorded_under_mask`): while it is true, a share of any other is a 409.

## Effective servers

- `https://api.saram.sh`

  Saram

## Authentication

- **HTTPBearer**: HTTP bearer

  a Saram API key (`sk_saram_<env>_...`) or a person's AuthKit access token, as `Authorization: Bearer <credential>`. Both are told apart by shape and produce the same principal.

## Path parameters

- **`run_id` (required)**: `string`

## Responses

### 200 Successful Response

**Content type:** `application/json`

schema: `ShareList`, no additional properties

A run's public links, revoked and expired ones included, newest first.

- **`mask_required` (required)**: `boolean`

  Whether a session of yours is shared only when the browser pool recorded it under its mask (SessionRow\.recorded\_under\_mask): a share of any other is refused with a 409. True for every customer; false only for Saram's own sessions, which are shared unmasked.
- **`public_shares` (required)**: `boolean`

  Whether your tenant may publish sessions at all. Off, a new link is refused with a 403 and no existing link plays; their rows are kept and they play again, until their own expiry, once it is back on.
- **`run_id` (required)**: `string`
- **`shares` (required)**: `array`

  **Items:**

  schema: `ShareSummary`, no additional properties

  One public link to a session's replay, as the list and the revocation answer it. Never the link itself.
  - **`created_at` (required)**: `string`, format: `date-time`
  - **`created_by` (required)**: `string`
  - **`expires_at` (required)**: `string`, format: `date-time`
  - **`id` (required)**: `string`
  - **`run_id` (required)**: `string`
  - **`session_id` (required)**: `string`
  - **`state` (required)**: `string`, possible values: `"live", "expired", "revoked"`

    live plays, expired and revoked do not. Read it beside ShareList.public\_shares: while your tenant's sharing is off no link plays, whatever its state.
  - **`token_hint` (required)**: `string`

    The link's last four characters, to tell your links apart.
  - **`view_count` (required)**: `integer`

    How many times the replay was opened. Nothing about who opened it is kept.
  - **`caller`**: `string | null`

    Who minted it, in words, when the credential had a name.
  - **`last_viewed_at`**: `string | null`, format: `date-time`
  - **`revoked_at`**: `string | null`, format: `date-time`
  - **`revoked_by`**: `string | null`

    Who revoked it: any principal of your tenant that may write runs can.

**Example:**

```json
{
  "run_id": "",
  "public_shares": true,
  "mask_required": true,
  "shares": [
    {
      "id": "",
      "run_id": "",
      "session_id": "",
      "token_hint": "",
      "state": "live",
      "created_at": "",
      "created_by": "",
      "caller": "",
      "expires_at": "",
      "revoked_at": "",
      "revoked_by": "",
      "view_count": 1,
      "last_viewed_at": ""
    }
  ]
}
```

### 403 the API key lacks the required scope

### 422 Validation Error

**Content type:** `application/json`

schema: `HTTPValidationError`

- **`detail`**: `array`

  **Items:**

  schema: `ValidationError`
  - **`loc` (required)**: `array of (string | integer)`
  - **`msg` (required)**: `string`
  - **`type` (required)**: `string`
  - **`ctx`**: `object`
  - **`input`**: `any`

**Example:**

```json
{
  "detail": [
    {
      "loc": [
        ""
      ],
      "msg": "",
      "type": "",
      "input": null,
      "ctx": {}
    }
  ]
}
```

## Schemas

- `HTTPValidationError` — shown above.
- `ShareList` — shown above.
- `ShareSummary` — shown above.
- `ValidationError` — shown above.