Usage endpoints

Use the usage endpoint to view details about your deployment's active nodes.

For information about how nodes are counted, which nodes are counted, node usage limitations, and monthly busting limits, refer to How nodes are counted.

GET /usage

Retrieves information about the orchestrator's daily node usage, Puppet events activity on nodes, and nodes that are present in PuppetDB.

Request format

When Forming orchestrator API requests to this endpoint, you can append parameters to the end of the URI path, such as:
https://orchestrator.example.com:8143/orchestrator/v1/usage?start_date=2022-01-01&end_date=2022_04_30&events=exclude
These parameters are available:
Parameter Definition
start_date Specify the earliest date to query, in YYYY-MM-DD format.
end_date Specify the latest date to query, in YYYY-MM-DD format. If you also specified start_date, the end_date must be greater than or equal to the start_date.
events Specifies whether you want the response to include or exclude daily Puppet events activity. The default is include.

If set to exclude, the response only contains node counts (total nodes and the number of nodes with and without agents). Specifically, the response omits the number of corrective changes, the number of intentional changes, the number of task runs, and the number of plan runs.

Response format

The response is a JSON object containing an array, called items, and an object, called pagination.

The pagination object contains the start_date and end_date parameters as supplied in the request.

The items array contains one JSON object for each day. Each object uses these keys to provide details about daily node usage:
Key Definition
date An ISO-8601 date representing the day in UTC.
total_nodes The total number of nodes used on a particular date, starting from midnight UTC. Unused or inactive nodes are not counted.
nodes_with_agent The number of unique nodes, out of the total_nodes, that have an agent installed. This is the number of nodes in PuppetDB on a particular date.
nodes_without_agent The number of unique nodes, out of the total_nodes, that do not have an agent installed.
corrective_agent_changes The number of corrective changes made by agent runs on a particular date.

Omitted if the request contained events=exclude.

intentional_agent_changes The number of intentional changes made by agent runs on a particular date.

Omitted if the request contained events=exclude.

nodes_affected_by_task_runs The number of tasks run (counted per node that a task runs on) on a particular date.

Omitted if the request contained events=exclude.

nodes_affected_by_plan_runs The number of plans run (counted per node that a plan runs on) on a particular date.

Omitted if the request contained events=exclude.

For example, this is a response to a request that contained events=exclude:
{
  "items":[
      {
        "date": "2018-06-08",
        "total_nodes": 100,
        "nodes_with_agent": 95,
        "nodes_without_agent": 5
      }, {
        "date": "2018-06-07",
        "total_nodes": 100,
        "nodes_with_agent": 95,
        "nodes_without_agent": 5
      }, {
        "date": "2018-06-06",
        "total_nodes": 100,
        "nodes_with_agent": 95,
        "nodes_without_agent": 5
      }, {
        "date": "2018-06-05",
        "total_nodes": 100,
        "nodes_with_agent": 95,
        "nodes_without_agent": 5
      }
  ],
  "pagination":{
     "start_date": "2018-06-01",
     "end_date": "2018-06-30"
  }
}

Error Responses

This endpoint's error responses follow the usual format for Orchestrator API error responses. The endpoint returns a 400 puppetlabs.orchestrator/validation-error response if there is a problem with a supplied parameter, such as the start_date parameter not having the proper date format.