Usage endpoints

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"
  }
}

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"
  }
}

Error Responses

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