# Ledger

## Get Account Ledger

Retrieves the ledger (account statement) for a specific account with cursor-based pagination and optional date filtering.

```
GET /account/:id/ledger
```

### Query Parameters

| Parameter | Type    | Default | Description                                      |
| --------- | ------- | ------- | ------------------------------------------------ |
| `from`    | String  | —       | Start date (`YYYY-MM-DD`) or datetime (ISO 8601) |
| `to`      | String  | —       | End date (`YYYY-MM-DD`) or datetime (ISO 8601)   |
| `cursor`  | Integer | —       | `account_version` (exclusive) from previous page |
| `limit`   | Integer | 50      | Items per page (1–200)                           |

### Response — `200 OK`

```json
{
  "account_id": "019702a0-...",
  "lines": [
    {
      "id": "019702a0-...-j1",
      "operation": "CREDIT",
      "transaction_id": "019702a0-...-tx1",
      "journal_entry_id": "019702a0-...-e1",
      "journal_entry_type": "PIX_IN",
      "journal_entry_sequence": 1,
      "asset": "BRL",
      "amount": 5000,
      "account_post_balance": 5000,
      "account_version": 1,
      "account_balance_policy": "NONE",
      "idempotency_key": "deposit-001",
      "created_at": "2026-01-15T10:30:00.123Z"
    },
    {
      "id": "019702a0-...-j2",
      "operation": "DEBIT",
      "transaction_id": "019702a0-...-tx2",
      "journal_entry_id": "019702a0-...-e2",
      "journal_entry_type": "PIX_OUT",
      "journal_entry_sequence": 1,
      "asset": "BRL",
      "amount": 1000,
      "account_post_balance": 4000,
      "account_version": 2,
      "account_balance_policy": "ALWAYS_POSITIVE",
      "idempotency_key": "payment-002",
      "created_at": "2026-01-15T11:00:00.456Z"
    }
  ]
}
```

### Pagination

Use cursor-based pagination via `account_version`:

**First page:**

```bash
curl "http://<host>:8080/account/<id>/ledger?limit=100" \
  -H "X-Api-Key: ak_..." \
  -H "X-Api-Secret: sk_..."
```

**Next page (using last version from previous response):**

```bash
curl "http://<host>:8080/account/<id>/ledger?cursor=100&limit=100" \
  -H "X-Api-Key: ak_..." \
  -H "X-Api-Secret: sk_..."
```

The `cursor` is exclusive — it returns lines with `account_version > cursor`.

### Date Filtering

```bash
# All lines in January 2026
curl "http://<host>:8080/account/<id>/ledger?from=2026-01-01&to=2026-01-31"

# Lines since a specific datetime
curl "http://<host>:8080/account/<id>/ledger?from=2026-01-15T10:00:00Z"

# Combine with pagination
curl "http://<host>:8080/account/<id>/ledger?from=2026-01-01&to=2026-01-31&cursor=50&limit=100"
```

### Errors

| HTTP | Code                | Cause                       |
| ---- | ------------------- | --------------------------- |
| 404  | `ACCOUNT_NOT_FOUND` | Account UUID does not exist |

### Understanding the Response

Each ledger line represents a single debit or credit operation on the account:

* **`operation: "DEBIT"`** — the amount was subtracted from this account's balance
* **`operation: "CREDIT"`** — the amount was added to this account's balance
* **`account_post_balance`** — the account balance immediately after this operation
* **`account_version`** — sequential counter, increments by 1 per operation

You can verify the balance evolution:

```
CREDIT: post_balance = previous_balance + amount
DEBIT:  post_balance = previous_balance - amount
```

{% hint style="info" %}
If ledger lines have been archived, the first available `account_version` in the live ledger may be greater than 1. Use the [Ledger Archive API](/docs/api-reference/ledger-archive.md) to access older data.
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://entrytarget.gitbook.io/docs/api-reference/ledger.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.