---
title: "Get a single bucket-scoped index registry entry"
method: GET
path: "/v3/_/indexes/{canonicalId}"
tags: ["Indexes"]
---

# Get a single bucket-scoped index registry entry

`GET /v3/_/indexes/{canonicalId}`

## Request

- Base URL: `http://localhost:9000`
- URL: `http://localhost:9000/v3/_/indexes/{canonicalId}`
- Auth: one of:
  - HTTP bearer
  - none

Returns the `Index` registry entry for a bucket-scoped index
(`Ledger == ""`, e.g. audit indexes). Ledger-scoped lookups go
through `GET /v3/{ledgerName}/indexes/{canonicalId}` — the two
keyspaces are distinct so a bucket-scoped lookup with the same
canonical will NotFound if only the ledger-scoped entry exists.
Requires `ledger:ReadOps` scope.

## Path parameters

- `canonicalId` string, required

## Headers

- `X-Consistency` 'linearizable' | 'stale'

## Response `200`

Index retrieved successfully.

- object
  - `data` object, required: Index (protobuf JSON representation)

## Other responses

- `400`: Bad request
- `401`: Authentication required (missing or invalid JWT token)
- `403`: Insufficient permissions (missing required scope)
- `404`: Not found
- `500`: Internal server error

## Changes

- **2026-11-03** `f5e817eca038`: 1 info
  - api operation id `getBucketIndex` removed and replaced with `v3GetBucketIndex`
- **2026-10-08** `3da23d327316`: 2 info
  - added the media type `text/plain` for the response with the status `401`
  - added the media type `text/plain` for the response with the status `403`
- **2026-10-08** `b3ee1959d86a`: 1 info
  - added the new optional `header` request parameter `X-Consistency`
- **2026-09-30** `b747efd5cd77`: 1 info
  - endpoint added
- **2026-09-29** `6ff73ac9a6bd`: 1 breaking
  - api path removed without deprecation

[Operation history](https://skmtc.dev/formancehq/apis/ledger-api/changes/v3/_/indexes/:canonicalId/get.md)

---

[API](https://skmtc.dev/formancehq/apis/ledger-api.md) - [All operations](https://skmtc.dev/formancehq/apis/ledger-api/llms.txt) - [OpenAPI document](https://skmtc.dev/formancehq/apis/ledger-api/revisions/f5e817eca038?raw)