Skip to main content

​
Overview

Brokers are the servers that handle message routing and storage in Pulsar. The Brokers API provides endpoints to monitor broker health, manage configurations, and view broker-level statistics. Base Path: /admin/v2/brokers

​
List Active Brokers

Get the list of all active broker IDs in a cluster. 
GET /admin/v2/brokers/{cluster}

​
Path Parameters

​
cluster
string
required
The cluster name

​
Response

​
brokers
array
Set of active broker IDs

​
Example

curl -X GET http://localhost:8080/admin/v2/brokers/us-west \
  -H "Authorization: Bearer <token>"

​
Response Example

[
  "broker-1.us-west.example.com:8080",
  "broker-2.us-west.example.com:8080",
  "broker-3.us-west.example.com:8080"
]

​
List Active Brokers (Local Cluster)

Get active brokers in the local cluster without specifying cluster name. 
GET /admin/v2/brokers

​
Example

curl -X GET http://localhost:8080/admin/v2/brokers \
  -H "Authorization: Bearer <token>"

​
Get Leader Broker

Retrieve information about the current leader broker. 
GET /admin/v2/brokers/leaderBroker

​
Response

​
serviceUrl
string
HTTP service URL of the leader broker
​
brokerId
string
The broker ID of the leader

​
Example

curl -X GET http://localhost:8080/admin/v2/brokers/leaderBroker \
  -H "Authorization: Bearer <token>"

​
Response Example

{
  "serviceUrl": "http://broker-1.us-west.example.com:8080",
  "brokerId": "broker-1.us-west.example.com:8080"
}

​
Get Owned Namespaces

Get the list of namespaces owned by a specific broker. 
GET /admin/v2/brokers/{clusterName}/{brokerId}/ownedNamespaces

​
Path Parameters

​
clusterName
string
required
The cluster name
​
brokerId
string
required
The broker ID (e.g., broker-1.example.com:8080)

​
Response

​
namespaces
object
Map of namespace names to ownership status

​
Example

curl -X GET http://localhost:8080/admin/v2/brokers/us-west/broker-1.example.com:8080/ownedNamespaces \
  -H "Authorization: Bearer <token>"

​
Response Example

{
  "my-tenant/ns1": {
    "broker_assignment": "shared",
    "is_controlled": false,
    "is_active": true
  },
  "my-tenant/ns2": {
    "broker_assignment": "primary",
    "is_controlled": true,
    "is_active": true
  }
}

​
Dynamic Configuration

​
Update Dynamic Configuration

Update a dynamic service configuration parameter. 
POST /admin/v2/brokers/configuration/{configName}/{configValue}

​
Path Parameters

​
configName
string
required
The configuration parameter name
​
configValue
string
required
The new value for the parameter

​
Example

curl -X POST http://localhost:8080/admin/v2/brokers/configuration/maxConcurrentLookupRequest/50000 \
  -H "Authorization: Bearer <token>"

​
Response Codes

CodeDescription
204Configuration updated successfully
403Don’t have super-user privileges
404Configuration not found
412Invalid configuration value
Only dynamic configurations can be updated at runtime. Static configurations require a broker restart.

​
Get All Dynamic Configurations

Retrieve all runtime configurations. 
GET /admin/v2/brokers/configuration/runtime

​
Example

curl -X GET http://localhost:8080/admin/v2/brokers/configuration/runtime \
  -H "Authorization: Bearer <token>"

​
Get Dynamic Configuration Names

Get the list of all dynamic configuration parameter names. 
GET /admin/v2/brokers/configuration

​
Example

curl -X GET http://localhost:8080/admin/v2/brokers/configuration \
  -H "Authorization: Bearer <token>"

​
Delete Dynamic Configuration

Reset a dynamic configuration to its default value. 
DELETE /admin/v2/brokers/configuration/{configName}

​
Example

curl -X DELETE http://localhost:8080/admin/v2/brokers/configuration/maxConcurrentLookupRequest \
  -H "Authorization: Bearer <token>"

​
Internal Configuration

​
Get Internal Configuration

Retrieve internal configuration data for the broker. 
GET /admin/v2/brokers/internal-configuration

​
Response

​
zookeeperServers
string
ZooKeeper connection string
​
configurationStoreServers
string
Configuration store connection string
​
ledgersRootPath
string
BookKeeper ledgers root path

​
Example

curl -X GET http://localhost:8080/admin/v2/brokers/internal-configuration \
  -H "Authorization: Bearer <token>"

​
Health Check

​
Health Check

Check broker health status. 
GET /admin/v2/brokers/health

​
Response Codes

CodeDescription
200Broker is healthy
307Temporary redirect to another broker
500Broker is unhealthy

​
Example

curl -X GET http://localhost:8080/admin/v2/brokers/health

​
Version

​
Get Pulsar Version

Get the Pulsar version running on the broker. 
GET /admin/v2/brokers/version

​
Response

​
version
string
Pulsar version string

​
Example

curl -X GET http://localhost:8080/admin/v2/brokers/version \
  -H "Authorization: Bearer <token>"

​
Response Example

"3.2.0"

​
Common Dynamic Configurations

Here are some commonly used dynamic configuration parameters:

​
Performance Tuning

  • maxConcurrentLookupRequest: Maximum concurrent topic lookup requests
  • maxConcurrentTopicLoadRequest: Maximum concurrent topic load requests
  • maxMessageSize: Maximum message size in bytes
  • maxPublishRatePerTopicInMessages: Max publish rate per topic
  • maxPublishRatePerTopicInBytes: Max publish rate per topic in bytes

​
Resource Limits

  • maxUnackedMessagesPerConsumer: Max unacked messages per consumer
  • maxUnackedMessagesPerSubscription: Max unacked messages per subscription
  • maxSubscriptionsPerTopic: Max subscriptions per topic
  • maxProducersPerTopic: Max producers per topic
  • maxConsumersPerTopic: Max consumers per topic

​
Backlog Management

  • backlogQuotaDefaultLimitGB: Default backlog quota in GB
  • backlogQuotaDefaultRetentionPolicy: Default retention policy (producer_request_hold, producer_exception, consumer_backlog_eviction)
  • backlogQuotaCheckIntervalInSeconds: How often to check backlog quotas

​
Example - Update Multiple Configurations

# Increase concurrent lookup limit
curl -X POST http://localhost:8080/admin/v2/brokers/configuration/maxConcurrentLookupRequest/100000 \
  -H "Authorization: Bearer <token>"

# Set max message size to 5MB
curl -X POST http://localhost:8080/admin/v2/brokers/configuration/maxMessageSize/5242880 \
  -H "Authorization: Bearer <token>"

# Set max producers per topic
curl -X POST http://localhost:8080/admin/v2/brokers/configuration/maxProducersPerTopic/10 \
  -H "Authorization: Bearer <token>"

​
Best Practices

​
Monitoring

  • Regularly check broker health endpoints
  • Monitor owned namespaces for balanced distribution
  • Track dynamic configuration changes
  • Set up alerts for broker failures

​
Configuration Management

  • Test configuration changes in staging first
  • Document all dynamic configuration updates
  • Use version control for configuration changes
  • Monitor impact of configuration changes

​
Performance

  • Tune concurrent request limits based on load
  • Adjust resource limits to prevent overload
  • Configure appropriate backlog policies
  • Monitor and adjust based on metrics

​
High Availability

  • Ensure multiple brokers per cluster
  • Monitor leader broker status
  • Test failover procedures
  • Balance namespace ownership across brokers

​
Error Handling

You don’t have super-user privileges.Solution: Ensure you’re authenticated with proper credentials.
The specified configuration parameter doesn’t exist.Solution: Check the list of available dynamic configurations.
The provided value is not valid for the configuration parameter.Solution: Check the parameter’s type and valid range.
The broker failed its health check.Solution: Check broker logs and system resources.

Clusters API

Manage cluster configurations

Namespaces API

View namespace ownership and policies

Build docs developers (and LLMs) love

Get started for freeTalk to us