<commit_before>---
title: "PuppetDB: Nodes endpoint"
layout: default
canonical: "/puppetdb/latest/api/query/v4/nodes.html"
---

[resource]: ./resources.html
[curl]: ../curl.html#using-curl-from-localhost-non-sslhttp
[statuses]: {{puppet}}/format_report.html#puppettransactionreport
[paging]: ./paging.html
[query]: ./query.html
[8601]: http://en.wikipedia.org/wiki/ISO_8601
[subqueries]: ./ast.html#subquery-operators
[ast]: ./ast.html
[factsets]: ./factsets.html
[reports]: ./reports.html
[catalogs]: ./catalogs.html
[facts]: ./facts.html
[fact-contents]: ./fact-contents.html
[events]: ./events.html
[edges]: ./edges.html
[resources]: ./resources.html
[inventory]: ./inventory.html

Nodes can be queried by making an HTTP request to the `/nodes` endpoint.

## `/pdb/query/v4/nodes`

This will return all nodes matching the given query. Deactivated and expired
nodes aren't included in the response.

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

To query for the latest fact/catalog/report timestamp submitted by 'example.local', the JSON query structure would be:

    ["=", "certname", "example.local"]

### Query operators

See [the AST query language page][ast].

### Query fields

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

* `certname` (string): the name of the node that the report was received from.

* `catalog_environment` (string): the environment for the last received catalog.

* `facts_environment` (string): the environment for the last received fact set.

* `report_environment` (string): the environment for the last received report.

* `catalog_timestamp` (timestamp): the last time a catalog was received. Timestamps are always [ISO-8601][8601] compatible date/time strings.

* `facts_timestamp` (timestamp): the last time a fact set was received. Timestamps are always [ISO-8601][8601] compatible date/time strings.

* `report_timestamp` (timestamp): the last time a report run was complete. Timestamps are always [ISO-8601][8601] compatible date/time strings.

* `latest_report_status` (string): the status of the latest report. Possible values
  come from Puppet's report status, which can be found [here][statuses].

* `latest_report_noop` (boolean): indicates whether the most recent report for
  the node was a noop run.

* `latest_report_noop_pending` (boolean): indicates whether the most recent
  report for the node contained noop events.

* `latest_report_corrective_change` (boolean): a flag indicating whether the latest
  report for the node included events that remediated configuration drift. This
  field is only populated in PE.

* `cached_catalog_status` (string): Cached catalog status of the
  last puppet run for the node. Possible values are `explicitly_requested`,
  `on_failure`, `not_used` or `null`.

* `latest_report_hash` (string): a hash of the latest report for the node.

* `latest_report_job_id` (string): the job id associated with the latest report (not present if the run wasn't part of a job).

* `["fact", <FACT NAME>]` (string, number, Boolean): the value of `<FACT NAME>` for a node. Inequality operators are allowed, and will skip non-numeric values.

    Note that nodes which are missing a fact referenced by a `not` query will match
    the query.

### Response format

The response is a JSON array of hashes, where each hash has the form:

    {
     "certname": <string>,
     "deactivated": <timestamp or null>,
     "expired": <timestamp or null>,
     "catalog_timestamp": <timestamp or null>,
     "facts_timestamp": <timestamp or null>,
     "report_timestamp": <timestamp or null>,
     "catalog_environment": <string or null>,
     "facts_environment": <string or null>,
     "report_environment": <string or null>,
     "latest_report_status": <string>,
     "latest_report_noop": <boolean>,
     "latest_report_noop_pending": <boolean>,
     "latest_report_hash": <string>,
     "latest_report_job_id": <string or null><commit_msg>(PDB-4271) Document fact expiration query fields<commit_after>---
title: "PuppetDB: Nodes endpoint"
layout: default
canonical: "/puppetdb/latest/api/query/v4/nodes.html"
---

[resource]: ./resources.html
[curl]: ../curl.html#using-curl-from-localhost-non-sslhttp
[statuses]: {{puppet}}/format_report.html#puppettransactionreport
[paging]: ./paging.html
[query]: ./query.html
[8601]: http://en.wikipedia.org/wiki/ISO_8601
[subqueries]: ./ast.html#subquery-operators
[ast]: ./ast.html
[factsets]: ./factsets.html
[reports]: ./reports.html
[catalogs]: ./catalogs.html
[facts]: ./facts.html
[fact-contents]: ./fact-contents.html
[events]: ./events.html
[edges]: ./edges.html
[resources]: ./resources.html
[inventory]: ./inventory.html
[expirev1]: ../../wire_format/configure_expiration_format_v1.html

Nodes can be queried by making an HTTP request to the `/nodes` endpoint.

## `/pdb/query/v4/nodes`

This will return all nodes matching the given query. Deactivated and expired
nodes aren't included in the response.

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

To query for the latest fact/catalog/report timestamp submitted by 'example.local', the JSON query structure would be:

    ["=", "certname", "example.local"]

### Query operators

See [the AST query language page][ast].

### Query fields

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

* `certname` (string): the name of the node that the report was received from.

* `catalog_environment` (string): the environment for the last received catalog.

* `facts_environment` (string): the environment for the last received fact set.

* `report_environment` (string): the environment for the last received report.

* `catalog_timestamp` (timestamp): the last time a catalog was received. Timestamps are always [ISO-8601][8601] compatible date/time strings.

* `facts_timestamp` (timestamp): the last time a fact set was received. Timestamps are always [ISO-8601][8601] compatible date/time strings.

* `report_timestamp` (timestamp): the last time a report run was complete. Timestamps are always [ISO-8601][8601] compatible date/time strings.

* `latest_report_status` (string): the status of the latest report. Possible values
  come from Puppet's report status, which can be found [here][statuses].

* `latest_report_noop` (boolean): indicates whether the most recent report for
  the node was a noop run.

* `latest_report_noop_pending` (boolean): indicates whether the most recent
  report for the node contained noop events.

* `latest_report_corrective_change` (boolean): a flag indicating whether the latest
  report for the node included events that remediated configuration drift. This
  field is only populated in PE.

* `cached_catalog_status` (string): Cached catalog status of the
  last puppet run for the node. Possible values are `explicitly_requested`,
  `on_failure`, `not_used` or `null`.

* `latest_report_hash` (string): a hash of the latest report for the node.

* `latest_report_job_id` (string): the job id associated with the latest report (not present if the run wasn't part of a job).

* `["fact", <FACT NAME>]` (string, number, Boolean): the value of `<FACT NAME>` for a node. Inequality operators are allowed, and will skip non-numeric values.

    Note that nodes which are missing a fact referenced by a `not` query will match
    the query.

* `expires_facts` (boolean): indicates whether or not factsets for the
  node will be a candidate for expiration.  This field will only be
  visible if the `include_facts_expiration` query parameter is set to
  `true`.

> *Note*: configuration of fact expiration is an experimental feature
> which might be altered or removed in a future release, and for the
> time being, PuppetDB exports will not include this information.

* `expires_facts_updated` (timestamp or null): indicates when the
  value of `expires_facts` was last changed.  This will be `null` if
  the value has never been explicitly set by a [configure expiration][expirev1]
  command.  This field will only be visible if the
  `include_facts_expiration` query parameter is set to true.

### Response format

The response is a JSON array of hashes, where each hash has the form:

    {
     "certname": <string>,
     "deactivated": <timestamp or null>,
     "expired": <timestamp or null>,
     "catalog_timestamp": <timestamp or null>,
     "facts_timestamp": <timestamp or null>,
     "report_timestamp": <timestamp or null>,
     "catalog_environment": <string or null>,
     "facts_environment": <string or null>,
     "report_environment": <string or null>,
     "latest_report_status": <string>,
     "latest_report_noop": <boolean>,
     "latest_report_noop_pending": <boolean>,
     "latest_report_hash": <string>,
     "latest_report_job_id": <string or null>
{'fraction_non_alphanumeric': 0.11097839070474536, 'fraction_numerical': 0.008144206754262135, 'mean_word_length': 4.564954682779456, 'pattern_counts': {'":': 28, '<': 41, '<?xml version=': 0, '>': 44, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1874108', 'n_tokens_mistral': 2717, 'n_tokens_neox': 2592, 'n_words': 1059}