# Netdata Agent Extractor (`datamule/netdata-agent-extractor`) Actor

Point at any open Netdata monitoring agent and export node info, the chart catalog, active alarms and fleet inventory from the public unauthenticated REST API. One actor over thousands of self-hosted Netdata nodes.

- **URL**: https://apify.com/datamule/netdata-agent-extractor.md
- **Developed by:** [Datamule](https://apify.com/datamule) (community)
- **Categories:** Developer tools
- **Stats:** 3 total users, 1 monthly users, 97.3% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.35 / 1,000 records

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## Netdata Agent Extractor

Point at **any open Netdata monitoring agent** and export its node info, metric
catalog, active alarms, or fleet inventory as a clean dataset — straight from the
public, unauthenticated Netdata REST API.

[Netdata](https://github.com/netdata/netdata) is the dominant real-time,
self-hosted infrastructure-monitoring agent (~74k★). It ships **open-by-default
without auth** — its threat model assumes the API port is unreachable from the
internet — so every exposed Agent serves the identical REST API. This one actor
therefore spans **every Netdata agent in existence**: no per-host scraper, no
host enumeration, no API key.

### Modes

Set `mode` to pick what to extract:

| mode | endpoint | one row per… |
|------|----------|--------------|
| `info` *(default)* | `/api/v1/info` | node — version, OS, kernel, CPU/RAM/disk, `hostsAvailable`, `chartsCount`, alarm counts, mirrored hosts |
| `charts` | `/api/v1/charts` | metric chart — id, name, type, family, context, title, units, `updateEvery`, `dimensionCount` |
| `alarms` | `/api/v1/alarms` | active health alarm — name, status, value, units, chart, `lastStatusChange`, info |
| `nodes` | `/api/v3/info` → `/api/v1/info` | agent / mirrored host — fleet inventory (package, OS, hardware, node counts) |

### Input

```json
{
  "sources": ["https://netdata.firehol.org"],
  "mode": "info",
  "chartFilter": "",
  "maxRecords": 100
}
```

- **`sources`** *(required)* — a list of Netdata base URLs (or full `…/api/v1/info`
  URLs). Point at one node or a whole list.
- **`mode`** — `info` (default) · `charts` · `alarms` · `nodes`.
- **`chartFilter`** — optional case-insensitive substring on a chart's id **and**
  context (charts mode only). e.g. `disk` matches `disk.io`, `app.disk_logical_io`, …
- **`maxRecords`** — optional global cap on emitted rows (each row is one billable event).
- **`bearer`** / **`extraHeaders`** — optional auth for a gated agent. Never required
  for public agents, never logged.

### Output

One flat, fully-typed row per record. Columns are shared across all modes (unused
columns are `null`), plus a lossless `_raw` object with the untouched source record
and `_source` / `_mode` / `_apiVersion` provenance. Example (`info` mode):

```json
{
  "_mode": "info",
  "hostname": "iplists.firehol.org",
  "version": "v2.10.0-643-nightly",
  "osName": "Debian GNU/Linux",
  "kernel": "6.1.0-49-amd64",
  "architecture": "x86_64",
  "virtualization": "kvm",
  "coresTotal": 2,
  "ramTotal": 4105359360,
  "chartsCount": 1773,
  "alarmsNormal": 156,
  "alarmsWarning": 0,
  "alarmsCritical": 0,
  "mirroredHosts": ["iplists.firehol.org"],
  "_source": "https://netdata.firehol.org/api/v1/info"
}
```

### Robustness

- **The parse is the moat.** The `/api/v1/info` schema is nightly-versioned and
  drifts across releases, so **every field is read by key presence** — a node
  omitting `container` / `cpu_freq` / `mirrored_hosts` yields `null`, never a
  crash. Netdata's string-encoded numerics (`"cores_total": "2"`) are coerced to
  integers; the nested `alarms` object is promoted to three integer columns.
- **Per-source resilience.** In a multi-source run, a host that is auth-gated
  (401/403), unreachable (Cloudflare 52x), timing out, or Cloud-only is **skipped
  with a warning** and the run continues — one bad host never fails the batch.
- **Honest failure.** A source that answers with a body that is *not* a Netdata
  API shape (an HTML error page, a wrong-shaped JSON object) is a clear fail-fast,
  so a misconfigured input never silently returns nothing.

### Pricing

Pay-per-event: **$0.0005 per record** (one emitted dataset row = one event).

### Scope

Netdata REST API only (`/api/v1/info`, `/api/v1/charts`, `/api/v1/alarms`,
`/api/v3/info`). Metric time-series *data* (`/api/v1/data`) and Netdata Cloud
(cloud-only nodes with no exposed Agent port) are out of scope.

# Actor input Schema

## `sources` (type: `array`):

One or more Netdata agent base URLs. Every Netdata agent (github.com/netdata/netdata) exposes the identical public JSON REST API (open-by-default, no auth), so one actor works against any of them. Give the bare base (https://netdata.firehol.org) — the actor appends the right /api path per mode — or a full /api/v1/info URL. Point it at a single node or a whole list.

## `mode` (type: `string`):

What to extract. info (default): one row per node from /api/v1/info (version, OS, hardware, hostsAvailable, chartsCount, alarm counts, mirrored hosts). charts: one row per metric chart from /api/v1/charts (id, context, family, units, dimensions). alarms: one row per active health alarm from /api/v1/alarms. nodes: fleet inventory — tries /api/v3/info (multi-node parent) and lists each agent, falling back to the mirrored-hosts of /api/v1/info.

## `chartFilter` (type: `string`):

Optional case-insensitive substring matched against each chart's id AND context; charts that contain it in neither are skipped. Used only in charts mode. Example: disk (matches disk.io, disk.space, disk\_space.\*, ...). Leave empty to include every chart.

## `maxRecords` (type: `integer`):

A GLOBAL cap on the number of rows to emit across all sources (each row is one billable event). Leave empty to emit everything. A single node's charts catalog can be 1000-2500+ rows, so a cap is useful when scanning charts.

## `bearer` (type: `string`):

Optional bearer token for a Netdata agent behind auth or an access list (sent as Authorization: Bearer \*\*\*). Not required for public agents. Never logged.

## `extraHeaders` (type: `object`):

Optional extra HTTP headers as a JSON object, e.g. {"x-api-key": "..."} or a cookie for a gated agent. Not required for public agents. Header values are never logged.

## Actor input object example

```json
{
  "sources": [
    "https://netdata.firehol.org"
  ],
  "mode": "info"
}
```

# Actor output Schema

## `results` (type: `string`):

No description

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "sources": [
        "https://netdata.firehol.org"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("datamule/netdata-agent-extractor").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "sources": ["https://netdata.firehol.org"] }

# Run the Actor and wait for it to finish
run = client.actor("datamule/netdata-agent-extractor").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "sources": [
    "https://netdata.firehol.org"
  ]
}' |
apify call datamule/netdata-agent-extractor --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,datamule/netdata-agent-extractor"
        }
    }
}

```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/K5oqQKk2WdA6wst5p/builds/HWhJJsdcxMxubiqse/openapi.json