Usage endpoints

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.

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