---
title: "List ledger subjects"
description: "Requires a workspace-bound API key with `ledger:read`. Lists workspace ledger subjects, newest first. Each subject includes its display label and any linked catalog entity. The display label uses the live preferred-label claim when available. With entityId, returns the subjects anchored to that entity in one bounded page. An anchor is an index between the workspace ledger and the shared catalog. It is neither a claim nor a merge. Unsupported or repeated query parameters are rejected with HTTP 400."
canonical: https://y2.dev/docs/api/reference/ontology-ledger/listLedgerSubjectsV2/
---

Endpoint Reference[Ontology Ledger](https://y2.dev/docs/api/reference/ontology-ledger)

# List ledger subjects

Requires a workspace-bound API key with \`ledger:read\`. Lists workspace ledger subjects, newest first. Each subject includes its display label and any linked catalog entity. The display label uses the live preferred-label claim when available. With entityId, returns the subjects anchored to that entity in one bounded page. An anchor is an index between the workspace ledger and the shared catalog. It is neither a claim nor a merge. Unsupported or repeated query parameters are rejected with HTTP 400.

`GET https://api.y2.dev/api/v2/ledger/subjects`

- Operation ID: `listLedgerSubjectsV2`
- Required scopes: `ledger:read`
- Contract: https://y2.dev/openapi.json

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `entityId` | query | string | No | Only subjects anchored to this public entity ID. |
| `limit` | query | integer | No |  |
| `cursor` | query | string | No | Opaque next cursor from the previous page. |

## Responses

| Status | Description | Body |
| --- | --- | --- |
| 200 | A page of ledger subjects. | `LedgerSubjectListResponse` |
| 400 | Invalid request parameters |  |
| 401 | Missing or invalid API key |  |
| 403 | Insufficient permissions or access denied |  |
| 404 | Resource not found |  |
| 429 | Rate limit exceeded (per-key or per-account aggregate) |  |
| 500 | Internal server error |  |

### 200 response fields

| Field | Type | Description |
| --- | --- | --- |
| `data[]` | array of `LedgerSubjectSummary` |  |
| `data[].id` | string |  |
| `data[].type` | string |  |
| `data[].class` | `LedgerSubjectClass` | Subjects never change class. An assessment would be another claim. |
| `data[].label` | string or null | Value of the live preferred-label designator, or null. |
| `data[].openedAt` | string (date-time) |  |
| `data[].anchor` | `LedgerEntityAnchor` or null |  |
| `meta` | `PublicListMeta` |  |
| `meta.count` | integer |  |
| `meta.pageCount` | integer |  |
| `meta.limit` | integer |  |
| `meta.isDone` | boolean |  |
| `meta.hasMore` | boolean |  |
| `meta.nextCursor` | string or null |  |
| `meta.asOf` | string (date-time) |  |
| `meta.page` | `PublicPageMeta` |  |
| `links` | `PublicCollectionLinks` |  |
| `links.self` | string |  |
| `links.next` | string or null |  |