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.

Examples

Using curl from localhost:

Get the factset for node “example.com”:

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

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

Paging

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.