# Dashboard: Get Stats
## Endpoint
`/api/dashboard/stats/get`
**Obsolete Path:** `/api/getStats`
## Method
GET
## Description
Returns the DNS stats that are displayed on the web console dashboard. Includes summary counters, time-series chart data (main chart, query response breakdown, query type breakdown, protocol type breakdown), and top-10 lists for clients, domains, and blocked domains.
## Authentication
Required. A session token obtained from `login` or `createToken`.
## Permissions
Dashboard: View
## Parameters
| `token` | string | Yes | - | The session token generated by the `login` or the `createToken` call. |
| `node` | string | No | Only usable when Clustering is initialized | The node domain name for which the stats data is needed. When unspecified, the current node is used. Set to `cluster` to get aggregate stats for the entire cluster. |
| `type` | string | No | - | The duration type. Valid values: `LastHour`, `LastDay`, `LastWeek`, `LastMonth`, `LastYear`, `Custom`. Default: `LastHour`. |
| `utc` | boolean | No | - | Set to `true` to return the main chart data with labels in UTC date time format, allowing conversion to local time using the received `labelFormat`. |
| `dontTrimQueryTypeData` | boolean | No | - | Set to `true` to get full data for the query type chart instead of the top 10 entries. Default: `false`. |
| `start` | string (ISO 8601) | No | Required when `type` is `Custom` | The start date in ISO 8601 format. Only applies when `type` is `Custom`. |
| `end` | string (ISO 8601) | No | Required when `type` is `Custom` | The end date in ISO 8601 format. Only applies when `type` is `Custom`. |
## Response Fields
The response is wrapped in `{ "response": { ... }, "status": "ok" }`.
### `response.stats` (object) -- Summary counters
| `totalQueries` | integer | Total number of DNS queries in the period. |
| `totalNoError` | integer | Total queries that returned NOERROR. |
| `totalServerFailure` | integer | Total queries that returned SERVFAIL. |
| `totalNxDomain` | integer | Total queries that returned NXDOMAIN. |
| `totalRefused` | integer | Total queries that returned REFUSED. |
| `totalAuthoritative` | integer | Total queries answered authoritatively. |
| `totalRecursive` | integer | Total queries resolved recursively. |
| `totalCached` | integer | Total queries answered from cache. |
| `totalBlocked` | integer | Total queries that were blocked. |
| `totalDropped` | integer | Total queries that were dropped. |
| `totalClients` | integer | Total unique clients in the period. |
| `zones` | integer | Number of hosted zones. |
| `cachedEntries` | integer | Number of cached DNS entries. |
| `allowedZones` | integer | Number of allowed zones. |
| `blockedZones` | integer | Number of blocked zones. |
| `allowListZones` | integer | Number of allow-list zones. |
| `blockListZones` | integer | Number of block-list zones. |
### `response.mainChartData` (object) -- Time-series chart
| `labelFormat` | string | Date/time format string for rendering labels (e.g., `"HH:mm"`). |
| `labels` | string[] | Array of UTC ISO 8601 timestamps (one per data point). |
| `datasets` | array of dataset objects | Each dataset represents a series. |
#### Dataset object
| `label` | string | Series name. Known values: `Total`, `No Error`, `Server Failure`, `NX Domain`, `Refused`, `Authoritative`, `Recursive`, `Cached`, `Blocked`, `Dropped`, `Clients`. |
| `backgroundColor` | string | RGBA background color for the chart. |
| `borderColor` | string | RGB border color for the chart. |
| `borderWidth` | integer | Border width in pixels. |
| `fill` | boolean | Whether to fill the area under the line. |
| `data` | integer[] | Array of integer values, one per label. |
### `response.queryResponseChartData` (object) -- Pie/doughnut chart
| `labels` | string[] | Category labels: `Authoritative`, `Recursive`, `Cached`, `Blocked`, `Dropped`. |
| `datasets` | array | Single-element array containing a dataset object. |
#### Dataset object
| `data` | integer[] | Count values corresponding to the labels. |
| `backgroundColor` | string[] | RGBA colors for each segment. |
### `response.queryTypeChartData` (object) -- Query type breakdown chart
| `labels` | string[] | DNS record type names (e.g., `A`, `AAAA`, `HTTPS`, `SOA`, `SRV`). Top 10 by default unless `dontTrimQueryTypeData=true`. |
| `datasets` | array | Single-element array containing a dataset object. |
#### Dataset object
| `data` | integer[] | Count values corresponding to the labels. |
| `backgroundColor` | string[] | RGBA colors for each segment. |
### `response.protocolTypeChartData` (object) -- Protocol breakdown chart
| `labels` | string[] | Protocol names (e.g., `Udp`, `Tcp`, `Tls`, `Https`, `Quic`). |
| `datasets` | array | Single-element array containing a dataset object. |
#### Dataset object
| `data` | integer[] | Count values corresponding to the labels. |
| `backgroundColor` | string[] | RGBA colors for each segment. |
### `response.topClients` (array of objects)
| `name` | string | Client IP address. |
| `domain` | string | (Optional) Reverse DNS name for the client. May be absent if reverse lookup fails or is unavailable. |
| `hits` | integer | Number of queries from this client. |
| `rateLimited` | boolean | Whether the client is currently being rate limited. |
### `response.topDomains` (array of objects)
| `name` | string | Domain name queried. |
| `hits` | integer | Number of queries for this domain. |
### `response.topBlockedDomains` (array of objects)
| `name` | string | Blocked domain name. |
| `hits` | integer | Number of blocked queries for this domain. |
## Conditional Logic Notes
- The `start` and `end` parameters are only meaningful when `type` is `Custom`. They are effectively ignored for other duration types.
- The `node` parameter can only be used when Clustering is initialized on the server. Setting it to `cluster` returns aggregate stats across all cluster nodes.
- When `utc` is `true`, the `labels` array in `mainChartData` contains UTC timestamps with the `labelFormat` field indicating how to render them. The client is expected to convert to local time.
- The `queryTypeChartData.labels` array is trimmed to the top 10 entries by default. Set `dontTrimQueryTypeData=true` to get the full list.
- The `topClients`, `topDomains`, and `topBlockedDomains` arrays each return up to 10 entries in this endpoint. Use `Get Top Stats` for larger result sets with configurable limits.
## Edge Cases
- The `domain` field in `topClients` entries is optional and may be absent when reverse DNS lookup does not resolve.
- The `type` parameter value `Custom` appears capitalized in the URL example but the docs also reference `custom` (lowercase) in the Get Top Stats section. Implementations should consider case-insensitive matching or use the capitalized form `Custom` to be safe.
- The `backgroundColor` arrays in pie/doughnut chart datasets may contain more color entries than there are data points (pre-allocated palette).
- An empty stats period will return zero-valued arrays rather than empty arrays.