---
title: "List S3 Grants"
method: GET
path: "/api/v1/admin/ledger/s3-grants"
tags: ["Admin APIs", "ledger"]
---

# List S3 Grants

`GET /api/v1/admin/ledger/s3-grants`

Every client's S3 awards, for Cole's oversight tab.

The same rows the client's own Vesting Schedule renders, from the same query — two
implementations of "accrued" or "progress" would drift, and the figure quoted to a client
has to be the one on their screen.

**Bounded, not paginated.** The cap is applied in SQL and everything downstream — the
vesting rollup, the debit attribution, the next-vest lookup — keys off the rows it returns,
so the database read is bounded and not merely the response. Ordering is deterministic
(client, effective_at, id), which is what makes real pagination a later addition rather than
a rewrite. ``has_more`` says outright whether anything was left behind — inferring it from
``total_grants == limit`` is wrong at the boundary, where a system holding exactly ``limit``
grants looks identical to one holding more.

## Query parameters

- `client_id` string, nullable — Narrow to one client; omit for every client.
- `limit` integer — Maximum grants to return, ordered by client then effective date.

## Response `200`

Successful Response

- S3AdminGrantsResponse
  - `grants` S3AdminGrantRow[], required
    - `grant_id` string, uuid, required
    - `client_id` string, uuid, nullable
    - `order_id` string, required
    - `award_date` string, date-time, nullable
    - `status` string, required
    - `vesting_kind` string, required
    - `block_contract_id` string, uuid, nullable
    - `block_request_id` string, uuid, nullable
    - `auto_apply` boolean
    - `allocated` string, required
    - `accrued` string, required
    - `consumed` string, required
    - `adjusted` string
    - `available` string, required
    - `periods_total` integer, required
    - `periods_issued` integer, required
    - `progress_pct` integer, required
    - `next_vest_at` string, date-time, nullable
    - `next_vest_amount` string, nullable
    - `client_name` string, nullable
  - `total_grants` integer, required
  - `has_more` boolean

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/carbonarc/apis/carbon-arc-client-admin-api.md) · [All operations](https://skmtc.net/carbonarc/apis/carbon-arc-client-admin-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/carbonarc/carbon-arc-client-admin-api/revisions/a8ca30023371/schema)