Factsets endpoint

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.


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 our guide to query structure.

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

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.

  • producer_timestamp (string): the most recent time of fact submission for the relevant certname from the Puppet Server.

  • producer (string): the certname of the Puppet Server that sent the factset to PuppetDB.

  • hash (string): a hash of the factset's certname, environment, timestamp, facts, and producer_timestamp.

Subquery relationships

The following list contains related entities that can be used to constrain the result set using implicit subqueries. For more information, consult the documentation for subqueries.

  • environments: the environment a factset was received from.

  • producers: the Puppet Server that sent the factset to PuppetDB.

Response format

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

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

  "certname": <node name>,
  "environment": <node environment>,
  "timestamp": <time of last fact submission>,
  "producer_timestamp": <time of command submission from Puppet Server>,
  "producer": <Puppet Server certname>
  "facts": <expanded facts>,
  "hash": <sha1 sum of "facts" value>

The <expanded facts> object is an expansion of the following form:

  "href": <url>,
  "data": [ {
    "name": <string>,
    "value": <any>
  } ... ]


Using curl from localhost:

Get the factset for node "example.com":

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

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

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

Get all factsets corresponding to nodes with uptime greater than 24 hours:

curl -X GET http://localhost:8080/pdb/query/v4/factsets \
  -d 'query=["in", "certname",
              ["extract", "certname",
                ["select_facts", ["and", ["=", "name", "uptime_hours"],
                                         [">", "value", 24]]]]]'

Which returns:

[ {
  "facts" : {
    "href": "/pdb/query/v4/factsets/desktop.localdomain/facts",
    "data": [
        "name": "blockdevice_sde_vendor",
        "value": "Generic"
        "name": "mtu_wlp5s0",
        "value": 1500
        "name": "processor6",
        "value": "Intel(R) Core(TM) i7-4790 CPU @ 3.60GHz"
        "name": "trusted",
        "value" : {
          "authenticated" : "remote",
          "certname" : "desktop.localdomain",
          "extensions" : { }
        "name": "system_uptime",
        "value": {
          "days" : 5,
          "hours" : 120,
          "seconds" : 433391,
          "uptime" : "5 days"
  "producer" : "server.localdomain",
  "producer_timestamp" : "2015-03-06T00:20:14.833Z",
  "timestamp" : "2015-03-06T00:20:14.918Z",
  "environment" : "production",
  "certname" : "desktop.localdomain",
  "hash" : "d118d161990f202e911b6fda09f79d24f3a5d4f4"
} ]


This will return the most recent factset for the given node. Supplying a node this way will restrict any given query to only apply to that node, but in practice this endpoint is typically used without a query string or URL parameters.

The result will be a single map of the factset structure described above, or a JSON error message if the factset is not found.


curl 'http://localhost:8080/pdb/query/v4/factsets/kb.local'

  "certname" : "kb.local",
  "environment" : "production",
  "facts" : {...},
  "hash" : "93253d31af6d718cf81f5bc028be2a671f23ed78",
  "producer" : "foo.local",
  "producer_timestamp" : "2015-06-04T15:27:56.893Z",
  "timestamp" : "2015-06-04T15:27:56.979Z"

curl -X GET http://localhost:8080/pdb/query/v4/factsets/my_fake_hostname

  "error" : "No information is known about factset my_fake_hostname"


This will return all facts for a particular factset, designated by a node certname.

This is a shortcut to the /facts endpoint. It behaves the same as a call to /facts with a query string of ["=", "certname", "<NODE>"], except results are returned even if the node is deactivated or expired.

URL parameters / query operators / query fields / response format

This route is an extension of the facts endpoint. It uses the same parameters, operators, fields, and response format.

If you provide a query parameter, it will specify additional criteria, which will be used to return a subset of the information normally returned by this route.


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