Docs Grey arrow pointing right Puppet Enterprise Grey arrow pointing right Orchestrating Puppet runs, tasks, and plans Grey arrow pointing right Orchestrator API v1 endpoints Grey arrow pointing right Usage endpoints Grey arrow pointing right

Usage endpoints

Sections

Use the /usage endpoint to view details about the active nodes in your deployment.

GET /usage

List the daily node usage of the orchestrator and nodes that are present in PuppetDB.

Parameters

Parameter Definition
start_date The first day to include in the result, in the format YYYY-MM-DD
end_date The last day to include in the result, in the format YYYY-MM-DD. The date must be >= start_date.
events Specifies whether to include or exclude the daily event details from the response. Defaults to include. When set to exclude, the keys corrective_agent_changes, intentional_agent_changes, nodes_affected_by_task_runs, and nodes_affected_by_plan_runs are removed.

Response format

The response is a JSON object indicating the total number of active nodes and subtotals of the nodes with and without an agent installed.

The following keys are used:
Key Definition
items Contains an array entries from most recent to least recent.
date An ISO 8601 date representing the date of the request in UTC.
total_nodes The total number of nodes used since UTC midnight.
nodes_with_agent The number of nodes in pdb at the time the request is made.
nodes_without_agent The number of unique nodes that don't have an agent that were used since UTC midnight.
corrective_agent_changes The number of corrective changes made by agent runs.
intentional_agent_changes The number of intentional changes made by agent runs.
nodes_affected_by_task_runs The number of tasks run (counted per node that a task runs on).
nodes_affected_by_plan_runs The number of plans run (counted per node that a plan runs on).
pagination An optional object that includes information about the original query.
start_date The starting day for the request (if specified).
end_date The last day requested (if specified).

For example:

{
  "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"
  }
}Copied!

When the events parameter is set to exlude, the response excludes the keys that specify Puppet events activity and only includes information about node counts.

For example: 
{
  "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"
  }
}Copied!

Error Responses

For this endpoint, the kind key of the error displays the conflict.