---
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`

## Request

- Base URL: `https://utxo-indexer.api.umbraprivacy.com`
- URL: `https://utxo-indexer.api.umbraprivacy.com/v1/trees/{tree_index}/utxos`
- Auth: none declared
- TypeScript: <https://skmtc.dev/umbra-defi/apis/umbra-indexer-read-service/docs/v1/trees/:tree_index/utxos/get.ts> (a function with typed inputs; its response is checked against the schema)

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.dev/umbra-defi/apis/umbra-indexer-read-service.md) - [All operations](https://skmtc.dev/umbra-defi/apis/umbra-indexer-read-service/llms.txt) - [OpenAPI document](https://skmtc.dev/umbra-defi/apis/umbra-indexer-read-service/revisions/ea7a4ee03e38?raw)