GET /api/reports/value

Use the GET /api/reports/value endpoint to retrieve information about time and money freed by Puppet Enterprise (PE) automation.

Request format

You must provide well-formed HTTP(S) requests. By default, the value API uses the standard HTTPS port for console communication, which is port 443. You can omit the port from your requests unless you want to specify a different port.

You must authenticate requests to the value API using your Puppet CA certificate and an RBAC token. The RBAC token must have viewing permissions for the console.

This is an example of a basic, authenticated value API request without any parameters:

curl -X GET --cacert "/etc/puppetlabs/puppet/ssl/certs/ca.pem" \
-H "X-Authentication: <RBAC_TOKEN>" \
"https://<HOSTNAME>/api/reports/value"

For general information about forming curl commands, authentication in commands, and Windows modifications, go to Using example commands.

You can use these parameters, attached with --data-urlencode, to modify your value API requests:

Parameter	Description	Default value
averageHourlySalary	Numeric value specifying average hourly salary to use to cost savings for automated work.	None
startDate	A date in yyyy-mm-dd format.	Today less nine days (One week plus two days in the past)
endDate	A daate in yyyy-mm-dd format. If you specify today's date, the response contains provisional data.	today less two days
minutesFreedPerCorrectiveChange	low, med, high, or any numeric value in minutes.	med
minutesFreedPerIntentionalChange	low, med, high, or any numeric value in minutes.	med
minutesFreedPerTaskRun	low, med, high, or any numeric value in minutes.	med
minutesFreedPerPlanRun	low, med, high, or any numeric value in minutes.	med

The numerical basis for minutesFreed parameters are controlled by Value report defaults.

Response format

The response is a JSON object listing details about time and cost freed. Responses use these keys:

Key	Definition
startDate	Start date for the reporting period.
endDate	End date for the reporting period.
totalCorrectiveChanges	Total number of corrective changes made during the reporting period.
minutesFreedByCorrectiveChanges	Total number of minutes freed by automated changes that prevent drift during regular Puppet runs. The calculation is based on the average minutes saved per change, as specified by the minutesFreedPerCorrectiveChange query parameter.
totalIntentionalChanges	Total number of intentional changes made during the reporting period.
minutesFreedByIntentionalChanges	Total number of minutes freed by automated changes based on new values or Puppet code. This calculation is based on the average minutes saved per change, as specified by the minutesFreedPerIntentionalChange query parameter.
totalNodesAffectedByTaskRuns	Total number of nodes affected by successful task runs during the reporting period.
minutesFreedByTaskRuns	Total number of minutes freed by automated task runs. This calculation is based on the average minutes saved per task run, as specified by the minutesFreedPerTaskRun query parameter.
totalNodesAffectedByPlanRuns	Total number of nodes affected by successful plan runs during the reporting period.
minutesFreedByPlanRuns	Total number of minutes freed by automated plan runs. This calculation is based on the average minutes saved per plan run, as specified by the minutesFreedPerPlanRun query parameter.
totalMinutesFreed	Total number of minutes free by all automated changes.
totalDollarsSaved	If the query specified an averageHourlySalary, total cost savings for all automated changes.

Request and response examples

This request generates a report for specified dates using the default time freed values:

curl -X GET --cacert "/etc/puppetlabs/puppet/ssl/certs/ca.pem" \
-H "X-Authentication: <RBAC_TOKEN>" \
-G "https://<HOSTNAME>/api/reports/value" \
--data-urlencode 'startDate=2020-07-08' \
--data-urlencode 'endDate=2020-07-15'

The result is:

{
  "startDate": "2020-07-08",
  "endDate": "2020-07-15",
  "totalCorrectiveChanges": 0,
  "minutesFreedByCorrectiveChanges": 0,
  "totalIntentionalChanges": 18,
  "minutesFreedByIntentionalChanges": 1620,
  "totalNodesAffectedByPlanRuns": 0,
  "totalNodesAffectedByTaskRuns": 0,
  "minutesFreedByPlanRuns": 0,
  "minutesFreedByTaskRuns": 0,
  "totalMinutesFreed": 1620
}

This request generates cost savings using default report dates and time freed values:

curl -X GET --cacert "/etc/puppetlabs/puppet/ssl/certs/ca.pem" \
-H "X-Authentication: <rbac token>" \
-G "https://<pe-console-fqdn>/api/reports/value" \
--data-urlencode 'averageHourlySalary=40'

The result is:

{
  "startDate": "2020-07-08",
  "endDate": "2020-07-15",
  "totalCorrectiveChanges": 0,
  "minutesFreedByCorrectiveChanges": 0,
  "totalIntentionalChanges": 18,
  "minutesFreedByIntentionalChanges": 1620,
  "totalNodesAffectedByPlanRuns": 0,
  "totalNodesAffectedByTaskRuns": 0,
  "minutesFreedByPlanRuns": 0,
  "minutesFreedByTaskRuns": 0,
  "totalMinutesFreed": 1620,
  "totalDollarsSaved": 1080,
}

This request generates a report with custom values for time freed:

curl -X GET --cacert "/etc/puppetlabs/puppet/ssl/certs/ca.pem" \
-H "X-Authentication: $(cat ~/.puppetlabs/token)" \
-G "https://<pe-console-fqdn>/api/reports/value" \
--data-urlencode 'minutesFreedPerCorrectiveChange=10' \
--data-urlencode 'minutesFreedPerIntentionalChange=20' \
--data-urlencode 'minutesFreedPerTaskRun=30' \
--data-urlencode 'minutesFreedPerPlanRun=40' 

The result is:

{
  "startDate": "2020-07-01",
  "endDate": "2020-07-08",
  "totalCorrectiveChanges": 1,
  "minutesFreedByCorrectiveChanges": 10,
  "totalIntentionalChanges": 2,
  "minutesFreedByIntentionalChanges": 40,
  "totalNodesAffectedByTaskRuns": 3,
  "minutesFreedByTaskRuns": 90,
  "totalNodesAffectedByPlanRuns": 4,
  "minutesFreedByPlanRuns": 160,
  "totalMinutesFreed": 300
}