---
title: "List a team’s shares ledger"
method: GET
path: "/api/v1/teams/{teamId}/shares"
tags: ["Teams"]
---

# List a team’s shares ledger

`GET /api/v1/teams/{teamId}/shares`

## Request

- Base URL: `https://charm.ing`
- URL: `https://charm.ing/api/v1/teams/{teamId}/shares`
- Auth: one of:
  - HTTP bearer
  - API key in cookie `__Secure-better-auth.session_token`

User-gated (`chrm_user_*` or session); the caller must be an owner/admin of the team. Unions grants, invitations, and live share links across every app the team owns, newest first unless `sort` says otherwise.

## Path parameters

- `teamId` string, required

## Query parameters

- `limit` integer
- `appId` string
- `q` string
- `scope` 'internal' | 'external'
- `kind` 'person' | 'invite' | 'link'
- `range` 7 | 30 | 90
- `sort` 'createdAt:desc' | 'createdAt:asc' | 'app:asc' | 'app:desc' | 'grantee:asc' | 'grantee:desc' | 'status:asc' | 'status:desc'
- `cursor` string
- `format` 'csv'

## Response `200`

The team’s shares ledger, as JSON or (with `format=csv`) as `text/csv`.

- ShareLedgerResponse
  - `ok` true, required
  - `shares` ShareLedgerRow[], required
    - `id` string, required
    - `kind` 'person' | 'invite' | 'link', required
    - `appId` string, uuid, required
    - `appDisplayName` string, required
    - `grantee` string, nullable, required: Handle or email; null for a link (nobody is behind the door yet).
    - `granteeBadges` NameBadges, required: The marks Charming shows beside a person’s name, derived from live plans at read time.
      - `pro` boolean, required: True while the person pays for a plan on their own account.
      - `affiliation` object, nullable, required: The paid team the person shows beside their name, or null for none.
        - `name` string, required
        - `logoUrl` string, uri, required
    - `role` string, required
    - `scope` 'internal' | 'external', required
    - `status` 'pending' | 'accepted' | 'active' | 'redeemed' | 'revoked', required
    - `createdAtMs` integer, required
  - `hasMore` boolean, required: True when the team has more matching shares than this page returned.
  - `nextCursor` string, nullable, required: Pass back as `cursor`, with the same `sort`, for the next page. Null on the last page.

## Other responses

- `400`: Invalid `limit`, `scope`, `kind`, `range`, `sort`, or `cursor`.
- `401`: Sign-in required.
- `403`: The caller is not an owner/admin of this team.

---

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