---
title: "Paginated global UTXO query"
method: GET
path: "/v1/utxos"
tags: ["utxos"]
---

# Paginated global UTXO query

`GET /v1/utxos`

Returns a paginated list of UTXO records in ascending `absolute_index` order,
spanning all Merkle trees.

**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): `UtxoResponse` -- self-contained `UtxoDataItem`
  sub-messages.
- **Columnar** (`X-Response-Layout: columnar`): `UtxoColumnarResponse` --
  parallel field arrays. Smaller wire size; preferred for bulk transfers.

## Absolute Index

```
absolute_index = tree_index * MAX_LEAVES_PER_TREE + insertion_index
```
where `MAX_LEAVES_PER_TREE = 1,048,576`.

## Pagination

Use `next_cursor` from each response as `start` for the next page.
Default page size: **1,000**. Maximum: **5,000** (`limit > 5000` -> `400`).

## Query parameters

- `start` integer
- `end` integer
- `limit` integer

## Headers

- `X-Response-Layout` 'columnar'

## Response `200`

UTXO records for the requested absolute index range.

## Other responses

- `400` — Invalid pagination parameters (e.g. `limit > 5000`, `start > end`).
- `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)