You can query factsets by making an HTTP request to the /factsets endpoint.

A factset is the set of all facts for a single certname.

Note: The v4 API is experimental and may change without notice. For stability, we recommend that you use the v3 API instead.

GET /v4/factsets

This will return all factsets matching the given query.

URL Parameters

  • query: Optional. A JSON array containing the query in prefix notation (["<OPERATOR>", "<FIELD>", "<VALUE>"]). See the sections below for the supported operators and fields. For general info about queries, see the page on query structure.

    If a query parameter is not provided, all results will be returned.

Query Operators

See the Operators page.

Query Fields

  • certname (string): the certname associated with the factset
  • environment (string): the environment associated with the fact
  • timestamp (string): the most recent time of fact submission from the associated certname

Response Format

Successful responses will be in application/json. Errors will be returned as non-JSON string.

The result will be a JSON array with one entry per certname. Each entry is of the form:

  "certname": <node name>,
  "environment": <node environment>,
  "timestamp": <time of last fact submission>,
  "facts": <facts for node>

The value of “facts” is a map describing facts for the node. The array is unsorted.


Using curl from localhost:

Get the factset for node “”:

curl -X GET http://puppetdb:8080/v4/factsets --data-urlencode 'query=["=", "certname", ""]'

Get all factsets with updated after “2014-07-21T16:13:44.334Z”:

curl -X GET http://puppetdb:8080/v4/factsets --data-urlencode 'query=[">",
"timestamp", "2014-07-21T16:13:44.334Z"]

Get all factsets corresponding to nodes running Darwin:

curl -X GET http://puppetdb:8080/v4/factsets --data-urlencode 'query=["in",
"certname", ["extract", "certname", ["select-facts", ["and", ["=", "name",
"operatingsystem"], ["=", "value", "Darwin"]]]]]'

which returns

[ {
  "facts" : {
    "operatingsystem" : "Darwin",

    <additional facts>

  "timestamp" : "2014-07-25T16:39:06.265Z",
  "environment" : "production",
  "certname" : "desktop.localdomain"
} ]


This query endpoint supports paged results via the common PuppetDB paging URL parameters. For more information, please see the documentation on paging.

Back to top
The page rank or the 1 our of 5 rating a user has given the page.
The email address of the user submitting feedback.
The URL of the page being ranked/rated.