1---
2title: "State overview endpoint"
3layout: default
4canonical: "/puppetdb/latest/api/query/v4/state-overview.html"
5---
6
7# State overview endpoint
8
9[event-counts]: ./event-counts.markdown
10[events]: ./events.markdown
11[curl]: ../curl.markdown
12[query]: query.markdown
13
14> **PE-only**: The state-overview endpoint is only available for Puppet
15> Enterprise.
16
17The state-overview endpoint provides a convenient mechanism for getting counts
18of nodes based on the status of their last report, or alternatively whether the
19node is unresponsive or has not reported.
20
21## `/pdb/ext/v1/state-overview`
22
23### URL parameters
24
25* `unresponsive_threshold`: required. The time (in seconds) since the last
26  report after which a node is considered "unresponsive".
27
28### Query operators
29
30This endpoint accepts no queries.
31
32### Response format
33
34Successful responses will be in `application/json`. Errors will be returned as
35non-JSON strings.
36
37The result will be a JSON hash of the following form:
38
39    {
40      "unresponsive": <number of nodes that have not reported since `unresponsive_threshold`>,
41      "unreported": <number of nodes for which PuppetDB has not received a report>,
42      "noop": <number of nodes for which the latest report was a noop>,
43      "failed": <number of nodes for which the latest report had failures>,
44      "unchanged": <number of nodes for which the latest report made no changes>,
45      "changed": <number of nodes for which the latest report had successful changes>
46    }
47
48The statuses are assessed by evaluating the following precedence rules in order:
49* If PuppetDB does not contain a report for a node, the status will be `unreported`
50* If a report has not been received within the `unresponsive_threshold`, the
51  node will be marked `unresponsive`.
52* Otherwise, the status will be assessed based on the most recent report in
53  PuppetDB.
54
55### Examples
56
57    curl -X GET http://localhost:8080/pdb/ext/v1/state-overview?unresponsive_threshold=3600
58
59    {
60      "unresponsive": 0,
61      "unreported": 0,
62      "noop": 10,
63      "failed": 3,
64      "unchanged": 50,
65      "changed": 4
66    }
67