---
title: "Fold a ledger subject"
description: "Requires a workspace-bound API key with ledger:read. Returns the fold of one subject: the head of every claim key that touches it. recordedAt selects what the ledger had recorded by then. ValidAt keeps only heads whose valid interval contains that time. A designation outside validAt moves to unlinkedDesignations instead of disappearing. Retracted heads are listed separately. A pair with both a live same-as and a live distinct-from is contested. The fold picks no winner and never merges rows. Reads are bounded. Truncated is true when a budget was reached."
canonical: https://y2.dev/docs/api/reference/ontology-ledger/getLedgerSubjectV2/
---

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

# Fold a ledger subject

Requires a workspace-bound API key with ledger:read. Returns the fold of one subject: the head of every claim key that touches it. recordedAt selects what the ledger had recorded by then. ValidAt keeps only heads whose valid interval contains that time. A designation outside validAt moves to unlinkedDesignations instead of disappearing. Retracted heads are listed separately. A pair with both a live same-as and a live distinct-from is contested. The fold picks no winner and never merges rows. Reads are bounded. Truncated is true when a budget was reached.

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

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

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `subjectId` | path | string | Yes | Ledger subject ID (sbj_ and 24 hex characters, from the public-ID digest strategy). |
| `recordedAt` | query | string (date-time) | No | Record-time cursor (ISO 8601). Omit for the latest record. |
| `validAt` | query | string (date-time) | No | Valid-time cursor (ISO 8601). Omit to ignore valid intervals. |

## Responses

| Status | Description | Body |
| --- | --- | --- |
| 200 | The subject's fold at the requested clocks. | `LedgerSubjectResponse` |
| 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` | `LedgerSubject` |  |
| `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 |  |
| `data.cursor` | object |  |
| `data.designations[]` | array of `LedgerDesignation` |  |
| `data.unlinkedDesignations[]` | array of `LedgerDesignation` | Designations whose valid interval excludes validAt. The string is not forgotten. |
| `data.claims[]` | array of `LedgerClaim` | Live heads that touch the subject or its designators. |
| `data.retracted[]` | array of `LedgerClaim` |  |
| `data.contested[]` | array of object |  |
| `data.counterparts[]` | array of `LedgerSubjectSummary` |  |
| `data.designators[]` | array of `LedgerDesignator` |  |
| `data.evidence[]` | array of `LedgerObservation` |  |
| `data.truncated` | boolean |  |