---
title: "Get shadow box broker status"
method: GET
path: "/v1/shadow-box/broker-status"
tags: ["Shadow Box"]
---

# Get shadow box broker status

`GET /v1/shadow-box/broker-status`

## Request

- Base URL: `https://{dataplane_api_url}`
- URL: `https://{dataplane_api_url}/v1/shadow-box/broker-status`
- Auth: OAuth 2
  - Implicit: `https://auth.prd.cloud.redpanda.com/oauth/authorize`

Get one broker's copy of the shadow box. Works while the controller has no leader.

## Query parameters

- `node_id` integer

## Response `200`

OK

- GetShadowBoxBrokerStatusResponse: `GetShadowBoxBrokerStatusResponse` is the response from the `GetShadowBoxBrokerStatus` RPC.
  - `broker` ShadowBoxBrokerStatus: One broker's copy of the shadow box.
    - `box` ShadowBox: The shadow box as one broker has installed it.
      - `revision` string, int64: Changes with each `Box`, `Unbox`, or `UpdateShadowBoxSettings` that changes something. Requests that change nothing, and completion, do not change it. `-1` until the first change.
      - `settings` ShadowBoxSettings: Settings that decide what a box covers and how it behaves.
        - `read_policy` ShadowBoxReadPolicy: How the box treats fetches from user topics in its scope.
          - `allow_all_reads` boolean: Lets every consumer keep fetching, so `exempt_principals` has no effect. Defaults to false.
          - `exempt_principals` string[]: Users who can still fetch while the box blocks reads, such as your shadow link's user. An empty name matches clients without SASL or mTLS. An empty list blocks every consumer.
        - `scope` ShadowBoxScope: Resources selected for shadow boxing.
          - `all_resources` AllResources: Selects every resource the box supports. Currently covers user topics, consumer groups, Schema Registry, ACLs, and Roles.
      - `state` 'SHADOW_BOX_STATE_UNBOXED' | 'SHADOW_BOX_STATE_BOXING' | 'SHADOW_BOX_STATE_BOXED' | 'SHADOW_BOX_STATE_UNBOXING': The state of the cluster's shadow box. - SHADOW_BOX_STATE_UNBOXED: No box is requested, and any `Unbox` has completed. - SHADOW_BOX_STATE_BOXING: Some brokers have not yet confirmed the latest change. Every broker counts, including brokers that are down. - SHADOW_BOX_STATE_BOXED: Every broker enforces the latest change and will keep enforcing it after a restart. Writes accepted before the box may still finish, transactions may remain open, and partition offsets may still advance. - SHADOW_BOX_STATE_UNBOXING: `Unbox` was requested, and some brokers have not yet confirmed that they stopped enforcing the box.
      - `state_changed_at` string, date-time, nullable: When `state` last changed, by the clock of the broker that recorded the change. Absent if the cluster has never been boxed or unboxed.
    - `error_message` string, nullable: Why the broker did not answer. Set only when `box` is absent.
    - `node_id` integer: The broker's node ID.

## Other responses

- `401`: Unauthenticated.
- `500`: Internal Server Error. Reach out to support.
- `default`: An unexpected error response.

## Changes

- **2026-10-30** `ff1b476fd533`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/redpanda-data/apis/redpanda-cloud-data-plane-api/changes/v1/shadow-box/broker-status/get.md)

---

[API](https://skmtc.dev/redpanda-data/apis/redpanda-cloud-data-plane-api.md) - [All operations](https://skmtc.dev/redpanda-data/apis/redpanda-cloud-data-plane-api/llms.txt) - [OpenAPI document](https://skmtc.dev/redpanda-data/apis/redpanda-cloud-data-plane-api/revisions/ff1b476fd533?raw)