| 1 | # API Tokens |
| 2 | |
| 3 | API tokens (Bearer tokens) enable you to access Netdata resources programmatically. These tokens authenticate and authorize API requests, allowing you to interact with Netdata services securely from external applications, scripts, or integrations. |
| 4 | |
| 5 | :::important |
| 6 | |
| 7 | API tokens never expire but should be managed carefully as they grant access to your Netdata resources. |
| 8 | |
| 9 | ::: |
| 10 | |
| 11 | ## Token Generation |
| 12 | |
| 13 | **Location** |
| 14 | |
| 15 | You can access token management through the Netdata UI: |
| 16 | |
| 17 | 1. Click your profile picture in the bottom-left corner |
| 18 | 2. Select "User Settings" |
| 19 | 3. Navigate to the API Tokens section |
| 20 | |
| 21 | **Available Scopes** |
| 22 | |
| 23 | You can limit each token to specific scopes that define its access permissions: |
| 24 | |
| 25 | | Scope | Description | API Access | |
| 26 | |:-----------------------|:---------------------------------------------------------------------------------------------------------------------------------------------------|:-----------------------------------| |
| 27 | | `scope:all` | Grants the same permissions as the user who created the token. Use case: Terraform provider integration. | Full access to all API endpoints | |
| 28 | | `scope:agent-ui` | Used by Agent for accessing the Cloud UI | Access to UI-related endpoints | |
| 29 | | `scope:grafana-plugin` | Used for the [Netdata Grafana plugin](https://github.com/netdata/netdata-grafana-datasource-plugin/blob/master/README.md) to access Netdata charts | Access to chart and data endpoints | |
| 30 | | `scope:mcp` | Used to connect MCP clients (Claude Desktop, Cursor, etc.) to [Netdata Cloud MCP](/docs/netdata-ai/mcp/README.md#netdata-cloud-mcp) for AI-assisted monitoring | Access to MCP server endpoints | |
| 31 | |
| 32 | ## API Versions |
| 33 | |
| 34 | Netdata provides three API versions that you can access with API tokens: |
| 35 | |
| 36 | - **v1**: The original API, focused on single-node operations |
| 37 | - **v2**: Multi-node API with advanced grouping and aggregation capabilities |
| 38 | - **v3**: The latest API version that combines v1 and v2 endpoints and may include additional features |
| 39 | |
| 40 | :::tip |
| 41 | |
| 42 | **v3 is the recommended version for Netdata Cloud queries.** Netdata Cloud v3 endpoints use POST with a JSON body and provide the most control over scoping, filtering, and aggregation. Local Agent v3 endpoints are available via GET; for example, `/api/v3/data` is query-parameter driven and does not use the Cloud v3 JSON body shape. See the [Common Endpoints section](#common-endpoints) for v3 endpoint details. |
| 43 | |
| 44 | ::: |
| 45 | |
| 46 | ## Common Endpoints |
| 47 | |
| 48 | With the appropriate token type, you can access endpoints including: |
| 49 | Cloud API tokens authenticate Netdata Cloud endpoints, while direct Local Agent endpoints use per-agent bearer tokens only when Agent bearer protection is enabled (and may not require a token when unprotected). |
| 50 | |
| 51 | | Surface | Method | Endpoint | Purpose | |
| 52 | |:----------------------------|:-------|:---------------------------------------------------|:-----------------------------------------------------------------| |
| 53 | | Netdata Cloud | `POST` | `/api/v3/spaces/{spaceID}/rooms/{roomID}/data` | Time-series metric data queries | |
| 54 | | Netdata Cloud | `POST` | `/api/v3/spaces/{spaceID}/rooms/{roomID}/nodes` | List nodes in a room | |
| 55 | | Netdata Cloud | `POST` | `/api/v3/spaces/{spaceID}/rooms/{roomID}/contexts` | List available metric contexts | |
| 56 | | Local Agent | `GET` | `/api/v3/data` | v3 data queries (single-node on an Agent, multi-node on a Parent) | |
| 57 | | Local Agent | `GET` | `/api/v3/nodes` | Multi-host node listing on a parent Agent | |
| 58 | | Local Agent | `GET` | `/api/v3/contexts` | List available metric contexts on an Agent | |
| 59 | | Local Agent | `GET` | `/api/v3/weights` | Metric scoring/correlation | |
| 60 | | Local Agent | `GET` | `/api/v3/q` | Full-text search | |
| 61 | | Netdata Cloud, Local Agent | `GET` | `/api/v2/nodes` | Node information | |
| 62 | | Netdata Cloud, Local Agent | `GET` | `/api/v2/data` | Multi-dimensional data queries | |
| 63 | | Netdata Cloud, Local Agent | `GET` | `/api/v2/contexts` | Context metadata | |
| 64 | | Netdata Cloud, Local Agent | `GET` | `/api/v2/weights` | Metric scoring/correlation | |
| 65 | | Netdata Cloud, Local Agent | `GET` | `/api/v2/q` | Full-text search | |
| 66 | | Local Agent | `GET` | `/api/v1/info` | Agent information | |
| 67 | | Local Agent | `GET` | `/api/v1/charts` | Legacy chart information | |
| 68 | | Local Agent | `GET` | `/api/v1/data` | Legacy single-node data queries | |
| 69 | |
| 70 | :::caution |
| 71 | |
| 72 | The local Agent `/api/v1/charts` endpoint is still available for backward compatibility, but it is deprecated for new integrations. Use `/api/v3/contexts` on local Agents, or `/api/v3/spaces/{spaceID}/rooms/{roomID}/contexts` in Netdata Cloud, to discover current metric contexts and dimensions. |
| 73 | |
| 74 | ::: |
| 75 | |
| 76 | :::note |
| 77 | |
| 78 | For Netdata Cloud metric queries, use the room-scoped **v3 POST endpoints** with a JSON body. Local Agents expose their own unscoped v3 endpoints such as `/api/v3/data`, `/api/v3/nodes`, `/api/v3/contexts`, `/api/v3/weights`, and `/api/v3/q`. Legacy metrics v1 endpoints such as `/api/v1/data` and `/api/v1/charts` remain local-Agent only and return **404** when called against `app.netdata.cloud`. v2 endpoints work on both Cloud and local Agents for backward compatibility, but v3 is recommended for Cloud. |
| 79 | |
| 80 | ::: |
| 81 | |
| 82 | ## Example Usage |
| 83 | |
| 84 | **Get the Netdata Cloud space list** |
| 85 | |
| 86 | ```console |
| 87 | curl -H 'Accept: application/json' -H "Authorization: Bearer <token>" https://app.netdata.cloud/api/v2/spaces |
| 88 | ``` |
| 89 | |
| 90 | **Get node information** |
| 91 | |
| 92 | ```console |
| 93 | curl -H 'Accept: application/json' -H "Authorization: Bearer <token>" https://app.netdata.cloud/api/v2/nodes |
| 94 | ``` |
| 95 | |
| 96 | **Query metric data** |
| 97 | |
| 98 | ```console |
| 99 | curl -H 'Accept: application/json' -H "Authorization: Bearer <token>" https://app.netdata.cloud/api/v2/data?contexts=system.cpu&after=-600 |
| 100 | ``` |
| 101 | |
| 102 | :::tip |
| 103 | |
| 104 | The examples above use v2 endpoints. For metric data queries, the v3 equivalent (`/api/v3/data`) is also available on local Agents and is used with query parameters. On Netdata Cloud, use the room-scoped v3 POST endpoint and JSON body — see the Advanced Metric Queries example below. |
| 105 | |
| 106 | ::: |
| 107 | |
| 108 | **Advanced Metric Queries with Aggregation** |
| 109 | |
| 110 | For more advanced queries with aggregation, use the POST endpoint with a JSON body. This allows you to query metrics with time aggregation (like average values) and control grouping and filtering. |
| 111 | |
| 112 | ```console |
| 113 | TOKEN="YOUR_API_TOKEN" |
| 114 | SPACE="YOUR_SPACE_ID" |
| 115 | ROOM="YOUR_ROOM_ID" |
| 116 | |
| 117 | read -r -d '' PAYLOAD <<'EOF' |
| 118 | { |
| 119 | "scope": {"contexts": ["system.cpu"]}, |
| 120 | "selectors": {"nodes": ["*"], "contexts": ["*"], "instances": ["*"], "dimensions": ["*"], "labels": ["*"], "alerts": ["*"]}, |
| 121 | "window": {"after": -600, "before": 0, "points": 5}, |
| 122 | "aggregations": { |
| 123 | "metrics": [{"group_by": ["selected"], "aggregation": "sum"}], |
| 124 | "time": {"time_group": "average"} |
| 125 | }, |
| 126 | "format": "json2", |
| 127 | "options": ["jsonwrap", "minify", "unaligned"], |
| 128 | "timeout": 30000 |
| 129 | } |
| 130 | EOF |
| 131 | |
| 132 | curl -s -X POST \ |
| 133 | -H 'Content-Type: application/json' \ |
| 134 | -H "Authorization: Bearer $TOKEN" \ |
| 135 | "https://app.netdata.cloud/api/v3/spaces/$SPACE/rooms/$ROOM/data" \ |
| 136 | -d "$PAYLOAD" |
| 137 | ``` |
| 138 | |
| 139 | **Time Aggregation Options** |
| 140 | |
| 141 | The `time_group` parameter in `aggregations.time` controls how data points within each time interval are combined: |
| 142 | |
| 143 | | Option | Description | Use Case | |
| 144 | |:-------------------|:-----------------------------------------------------------------------------------|:-----------------------------------------| |
| 145 | | `average` | Mean value (default) | Average resource consumption over time | |
| 146 | | `min` | Minimum value | Find lowest values in each interval | |
| 147 | | `max` | Maximum value | Find spikes or peaks | |
| 148 | | `sum` | Sum of values | Total volume transferred (counters) | |
| 149 | | `median` | Median value | Robust central tendency | |
| 150 | | `stddev` | Standard deviation | Measure of variability | |
| 151 | | `ses` | Single exponential smoothing | Trend-aware smoothing | |
| 152 | | `des` | Double exponential smoothing | Trend + seasonality smoothing | |
| 153 | | `incremental-sum` | Difference between last and first value | Change over interval | |
| 154 | | `percentile` | Generic percentile (set value in `time_group_options`) | e.g., 95th percentile latency | |
| 155 | | `countif` | Count values matching condition (set condition in `time_group_options`) | e.g., count samples above threshold | |
| 156 | | `trimmed-mean` | Mean after trimming outliers (set trim % in `time_group_options`) | Robust average excluding extremes | |
| 157 | | `trimmed-median` | Median after trimming outliers (set trim % in `time_group_options`) | Robust median excluding extremes | |
| 158 | | `extremes` | Min and max values | Show value range per interval | |
| 159 | |
| 160 | :::important |
| 161 | |
| 162 | When using `time_group` values other than `min`, `max`, `average`, or `sum`, you MUST specify `"tier": 0` in the `window` object to ensure a non-aggregated storage tier is used. Without it, the query may use a pre-aggregated tier (per-minute or per-hour) where advanced functions like `median`, `stddev`, `ses`, `des`, `percentile`, `countif`, `trimmed-mean`, `trimmed-median`, and `extremes` cannot work correctly. |
| 163 | |
| 164 | ::: |
| 165 | |
| 166 | **Get context information** |
| 167 | |
| 168 | ```console |
| 169 | curl -H 'Accept: application/json' -H "Authorization: Bearer <token>" https://app.netdata.cloud/api/v2/contexts |
| 170 | ``` |