Metrics API

Using the Metrics API

You can use the Metrics API to periodically poll for data about your cluster, hosts, containers, and applications. The Metrics API is one way to get metrics from DC/OS. It is designed for occasional targeted access to specific tasks and hosts. It is not the best way to get a comprehensive picture of all metrics on DC/OS. It is recommended to use the DC/OS Monitoring service to monitor all the metrics on your cluster.

The Metrics API is backed by Telegraf, which runs on all nodes in the cluster.

To get started with the DC/OS metrics component and how to use the Metrics API, see the Metrics Quick Start Guide.


Access to the Metrics API is proxied via Admin Router to each node. Statistics for the current leader are prefixed with:


IMPORTANT: /system/v1/metrics/v0/ is expected to 404 on masters.

Statistics for an agent are prefixed with:


To determine the URL of your cluster, see Cluster Access. The agent ID of a node is its Mesos ID.


The Metrics API request and response bodies are formatted in JSON.

Requests must include the accept header:

Accept: application/json

Responses will include the content type header:

Content-Type: application/json


All Metrics API routes require authentication to use.

To authenticate API requests, see Obtaining an authentication token and Passing an authentication token documentation.

The Metrics API also requires authorization via the following permissions:

Route Permission
/system/v1/metrics/v0/ dcos:adminrouter:ops:system-metrics
/system/v1/agent/{agent_id}/metrics/v0/ dcos:adminrouter:system:agent

All routes may also be reached by users with the dcos:superuser permission.

To assign permissions to your account, see the permissions reference documentation.


The following resources are available under both of the above routes: