Skip to main content
The Supervisor API allows you to manage and monitor supervisors for Apache Druid. Supervisors manage the lifecycle of streaming ingestion tasks from sources like Kafka and Kinesis.
In this documentation, the term “offset” refers to Kafka record identifiers. For Kinesis, the equivalent is “sequence number”.

​
Supervisor information

​
Get active supervisor IDs

Returns an array of active supervisor names. 
curl "http://ROUTER_IP:ROUTER_PORT/druid/indexer/v1/supervisor"

[
    "wikipedia_stream",
    "social_media"
]

​
Get active supervisor objects

Retrieves detailed information for all active supervisors including state, spec, and configuration. 
curl "http://ROUTER_IP:ROUTER_PORT/druid/indexer/v1/supervisor?full=null"
​
id
string
Unique supervisor identifier.
​
state
string
Generic supervisor state: UNHEALTHY_SUPERVISOR, UNHEALTHY_TASKS, PENDING, RUNNING, SUSPENDED, or STOPPING.
​
detailedState
string
Implementation-specific detailed state (e.g., CONNECTING_TO_STREAM for Kafka).
​
healthy
boolean
Health indicator for the supervisor.
​
spec
object
Complete supervisor configuration including dataSchema, ioConfig, and tuningConfig.

​
Get supervisor states

Retrieves state information for all active supervisors. 
curl "http://ROUTER_IP:ROUTER_PORT/druid/indexer/v1/supervisor?state=true"

[
    {
        "id": "wikipedia_stream",
        "state": "UNHEALTHY_SUPERVISOR",
        "detailedState": "UNABLE_TO_CONNECT_TO_STREAM",
        "healthy": false,
        "suspended": false
    },
    {
        "id": "social_media",
        "state": "RUNNING",
        "detailedState": "RUNNING",
        "healthy": true,
        "suspended": false
    }
]

​
Get supervisor specification

Retrieves the complete specification for a single supervisor. 
curl "http://ROUTER_IP:ROUTER_PORT/druid/indexer/v1/supervisor/wikipedia_stream"
​
supervisorId
string
required
The unique identifier of the supervisor.
​
type
string
Supervisor type (kafka or kinesis).
​
dataSchema
object
Data schema including timestamp spec, dimensions, and granularity.
​
ioConfig
object
I/O configuration including topic, consumer properties, and task settings.
​
tuningConfig
object
Tuning configuration for indexing performance.

​
Get supervisor status

Retrieves the current status report for a supervisor including task states and recent exceptions. 
curl "http://ROUTER_IP:ROUTER_PORT/druid/indexer/v1/supervisor/social_media/status"
​
supervisorId
string
required
The supervisor ID to check status for.
​
dataSource
string
Name of the datasource being ingested.
​
stream
string
Name of the Kafka topic or Kinesis stream.
​
partitions
integer
Number of partitions in the stream.
​
activeTasks
array
Array of currently running indexing tasks.
​
latestOffsets
object
Latest available offsets for each partition.
​
minimumLag
object
Minimum lag per partition between current offset and latest offset.
{
    "id": "social_media",
    "generationTime": "2023-07-05T23:24:43.934Z",
    "payload": {
        "dataSource": "social_media",
        "stream": "social_media",
        "partitions": 1,
        "activeTasks": [
            {
                "id": "index_kafka_social_media_ab72ae4127c591c_flcbhdlh",
                "startingOffsets": {
                    "0": 3176381
                },
                "currentOffsets": {
                    "0": 3296632
                },
                "lag": {
                    "0": 3
                }
            }
        ],
        "latestOffsets": {
            "0": 3296635
        },
        "aggregateLag": 3,
        "healthy": true,
        "state": "RUNNING"
    }
}

​
Get supervisor health

Retrieves the health status of a supervisor based on state and configuration thresholds. 
curl "http://ROUTER_IP:ROUTER_PORT/druid/indexer/v1/supervisor/social_media/health"
​
supervisorId
string
required
The supervisor ID to check health for.
{
    "healthy": true
}

​
Get supervisor ingestion stats

Returns current ingestion row counters and moving averages for each task managed by the supervisor. 
curl "http://ROUTER_IP:ROUTER_PORT/druid/indexer/v1/supervisor/custom_data/stats"
​
supervisorId
string
required
The supervisor ID to retrieve stats for.
​
movingAverages
object
Moving averages over 1m, 5m, and 15m windows.
​
totals
object
Total counts since task start.
{
    "0": {
        "index_kafka_custom_data_881d621078f6b7c_ccplchbi": {
            "movingAverages": {
                "buildSegments": {
                    "5m": {
                        "processed": 53.40,
                        "processedBytes": 5226.40,
                        "unparseable": 0.0
                    }
                }
            },
            "totals": {
                "buildSegments": {
                    "processed": 665,
                    "processedBytes": 65079,
                    "unparseable": 0
                }
            }
        }
    }
}

​
Audit history

​
Get audit history for all supervisors

Retrieves the audit history of supervisor configurations over a time period. 
curl "http://ROUTER_IP:ROUTER_PORT/druid/indexer/v1/supervisor/history"
​
interval
string
ISO-8601 time interval to limit results (e.g., 2023-07-13/2023-07-19).
​
count
integer
Limit the number of results to the last N entries.
​
key
string
Supervisor ID.
​
type
string
Type of change (typically “supervisor”).
​
auditInfo
object
Information about who made the change and when.
​
payload
string
JSON string of the supervisor specification.
​
auditTime
string
ISO-8601 timestamp of when the change was made.

Build docs developers (and LLMs) love

Get started for freeTalk to us