Puppet agent nodes submit reports after their runs, and the puppet master forwards these to PuppetDB. Each report includes:

  • Some data about the entire run
  • Some metadata about the report
  • Many events, describing what happened during the run

Once this information is stored in PuppetDB, it can be queried in various ways.

  • You can query data about the run and report metadata by making an HTTP request to the /reports endpoint.
  • You can query data about individual events by making an HTTP request to the /events endpoint.
  • You can query summaries of event data by making an HTTP request to the /event-counts or aggregate-event-counts endpoints.

GET /v3/reports

URL Parameters

  • query: Optional. A JSON array of query predicates, 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 the query parameter is absent, PuppetDB will return all reports.

Query Operators

See the Operators page

Query Fields

The below fields are allowed as filter criteria and are returned in all responses.

  • certname: the name of the node that the report was received from.

  • hash: the id of the report; these ids can be acquired via event queries (see the /events endpoint).

Response format

The response is a JSON array of report summaries for all reports that matched the input parameters. The array is unsorted.

    "end-time": "2012-10-29T18:38:01.000Z",
    "puppet-version": "3.0.1",
    "receive-time": "2012-10-29T18:38:04.238Z",
    "configuration-version": "1351535883",
    "start-time": "2012-10-29T18:38:00.000Z",
    "hash": "bd899b1ee825ec1d2c671fe5541b5c8f4a783472",
    "certname": "foo.local",
    "report-format": 4,
    "transaction-uuid": "030c1717-f175-4644-b048-ac9ea328f221"
    "end-time": "2012-10-26T22:39:32.000Z",
    "puppet-version": "3.0.1",
    "receive-time": "2012-10-26T22:39:35.305Z",
    "configuration-version": "1351291174",
    "start-time": "2012-10-26T22:39:31.000Z",
    "hash": "cd4e5fd8846bac26d15d151664a40e0f2fa600b0",
    "certname": "foo.local",
    "report-format": 4,
    "transaction-uuid": null


You can use curl to query information about reports like so:

curl -G 'http://localhost:8080/v3/reports' --data-urlencode 'query=["=", "certname", "example.local"]'


This query endpoint supports paged results via the common PuppetDB paging query 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.