---
title: "Paginated UTXO records for a specific tree"
method: GET
path: "/v1/trees/{tree_index}/utxos"
tags: ["trees", "utxos"]
---

# Paginated UTXO records for a specific tree

`GET /v1/trees/{tree_index}/utxos`

Returns a paginated page of UTXO records belonging to the specified Merkle
tree, ordered by `absolute_index` ascending (= insertion order).

**Always Protobuf** -- responds with `application/x-protobuf` regardless
of the `Accept` header.

## Response layout

Set the `X-Response-Layout` header to switch between encoding strategies:
- **Row-oriented** (default, `X-Response-Layout` absent or any other value):
  `UtxoResponse` -- each UTXO is a self-contained `UtxoDataItem` message.
- **Columnar** (`X-Response-Layout: columnar`): `UtxoColumnarResponse` --
  fields are transposed into parallel arrays. Smaller wire size and preferred
  by data-pipeline consumers.

## Pagination

The `cursor` parameter is an **absolute index** (not a tree-local insertion
index). Initialize it to `tree_index * MAX_LEAVES_PER_TREE` for the first
page, then use `next_cursor` from each response for subsequent pages.

## Path parameters

- `tree_index` integer, required

## Query parameters

- `cursor` integer
- `limit` integer

## Headers

- `X-Response-Layout` 'columnar'

## Response `200`

UTXO records for the specified tree.

## Other responses

- `400` — Invalid `tree_index` or pagination parameters.
- `429` — Rate limit exceeded.
- `500` — Storage backend error.

---

[API](https://skmtc.net/umbra-defi/apis/umbra-indexer-read-service.md) · [All operations](https://skmtc.net/umbra-defi/apis/umbra-indexer-read-service/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/umbra-defi/umbra-indexer-read-service/revisions/ea7a4ee03e38/schema)