Home › Topics › Monitoring APIs and Webhooks › Pulling Data Out

Pulling Data Out: Scripts That Read Your Monitoring System


Every admin has done the ritual. Open the monitoring console, click through to the device list, select all, copy, and paste into a spreadsheet. Fix the columns that came through wrong and send it to whoever asked. Next month, do it again. The monitoring system already holds the cleanest inventory you own, refreshed every few minutes, and yet it leaves the building by hand.


This guide is about ending the ritual. It shows how a short script can ask your monitoring system's API for devices, alerts, or metrics. The script can hand the answer to a spreadsheet, a report, a dashboard, or another script, on a schedule, without you. It assumes you have read APIs and webhooks in plain language. Or it assumes you at least know that an API is a front desk, a GET request is a question, and JSON is the envelope the answer comes in. By the end you will have working request patterns in three tools. You will know how to handle the four things that break beginner scripts: long lists, rate limits, errors, and timeouts.


Every endpoint in this guide is invented. https://monitor.example.local/api/devices stands in for whatever your product actually calls its device list. The shapes and habits are what transfer.


In this guide

  • What you can do once the data is out
  • One request, three tools
  • Asking for the next page
  • Being polite: rate limits and backing off
  • Filter on the server, and cache what does not change
  • Handling errors and timeouts
  • Getting it out and running it on a schedule
  • Patterns, examples, and gotchas
  • Where to go next

What you can do once the data is out


Four jobs account for nearly every read-only script ever written against a monitoring system, and each one is a good first project.


  • Syncing the device list. The monitor knows every device it watches, with addresses, types, and the last time each responded. A nightly pull can feed that into a configuration management database (a CMDB, the formal register of what you own) or a plain spreadsheet. That keeps the inventory from being more than a day old. Where the monitor's list and the inventory disagree, you have found either a forgotten device or a forgotten monitor. Both are worth knowing. The guide on keeping inventory current covers that reconciliation in depth.
  • Building a custom report. The console's built-in reports answer the questions the vendor imagined. A script that pulls availability or alert history and reshapes it answers the questions your manager actually asks. The Automating Reports guides cover the reporting side of that.
  • Feeding a dashboard. A wall screen or a small internal web page can show "open critical alerts" or "devices down". A script can feed it by polling the API every minute and writing a small JSON file the page reads.
  • Checking alert state from another script. A deployment or maintenance script can ask "are there open critical alerts on the systems I am about to touch?" before it starts. It can refuse to run if so. This is one of the cheapest, most effective safety interlocks you can build.

One request, three tools


All four jobs begin with the same act: send a GET request with a token, get JSON back. Here it is in the three tools admins actually use. Each asks for the device list from the invented server, presenting a token that you have stored somewhere safer than the script itself.


curl, for testing and one-liners

curl -s --fail-with-body \
     "https://monitor.example.local/api/devices?limit=50" \
     -H "Authorization: Bearer <TOKEN>" \
     -H "Accept: application/json"

-s keeps the progress bar out of your output. --fail-with-body makes curl return a non-zero exit code on a 4xx or 5xx response while still printing the error body. That lets both you and a calling script tell something went wrong. curl is the tool to reach for first: prove the token and the URL work here before you write anything longer.


PowerShell, for Windows shops

$token   = Get-Content "$env:ProgramData\monitor-sync\token.txt" -Raw
$headers = @{ Authorization = "Bearer $token"; Accept = "application/json" }

$resp = Invoke-RestMethod -Uri "https://monitor.example.local/api/devices?limit=50" `
                          -Headers $headers -Method Get -TimeoutSec 30

$resp.items | Select-Object id, name, address, type, status

Invoke-RestMethod is generous. It sends the request, checks the status code, and parses the JSON into objects you can pipe, filter, and export without any further work. The token comes from a file on disk with permissions locked to the account that runs the script. That is the minimum acceptable way to keep a credential out of the script text. The guide on API security and hygiene covers better options.


Python, for anything that grows

import os, requests

token   = os.environ["MONITOR_TOKEN"]
headers = {"Authorization": f"Bearer {token}", "Accept": "application/json"}

resp = requests.get("https://monitor.example.local/api/devices",
                    params={"limit": 50}, headers=headers, timeout=30)
resp.raise_for_status()
for device in resp.json()["items"]:
    print(device["id"], device["name"], device["status"])

The shape is the same: token from the environment, headers, a request with a timeout, and a check that the status was good. Here, raise_for_status stops the script on 4xx or 5xx. Then comes the parsed JSON. Whichever tool you choose, notice the three habits already present. The token is not in the code, there is a timeout, and the status is checked before the body is trusted.


Asking for the next page


The first surprise for most beginners is that the device list comes back short. You have four hundred devices; the API returned fifty. Nothing is wrong. Long lists are delivered in pages. That is because a single reply holding ten thousand alerts would be slow to build and slow to send. It would be painful for both sides if the connection dropped halfway. Each reply tells you how to ask for the next page. The three common styles:


  • Page numbers. You ask for ?page=1&per_page=50, then ?page=2, and so on until a page comes back empty or the reply says you are on the last one.
  • Offset and limit. You ask for ?offset=0&limit=50, then ?offset=50, adding the limit each time until fewer than fifty items return.
  • Cursors or next links. The reply includes an opaque token or a full URL for the next page; you use it exactly as given and stop when it is absent. This style copes best with lists that change while you are reading them.

A reply envelope in the cursor style might look like this:


{
  "items": [ { "id": 42, "name": "sw-core-01", "status": "up" }, ... ],
  "total": 412,
  "next": "https://monitor.example.local/api/devices?cursor=ab12cd"
}

And the loop that follows the trail, in PowerShell:


$all = @()
$url = "https://monitor.example.local/api/devices?limit=50"
while ($url) {
    $page = Invoke-RestMethod -Uri $url -Headers $headers -TimeoutSec 30
    $all += $page.items
    $url  = $page.next          # $null when there is no next page
}
"$($all.Count) devices fetched"

Two details deserve care. First, always put a ceiling on the loop, such as a maximum page count. That way, a bug in the API or in your code cannot spin forever. Second, ask for the largest page size the documentation allows. Fewer, bigger requests are kinder to the server than many small ones, which leads straight into rate limits.


Being polite: rate limits and backing off


A rate limit is the maximum number of requests the API will serve you in a period. It exists because the same server that answers your script is also collecting data from every device and drawing every dashboard. A script in a tight loop can starve the work that matters. When you exceed the limit, the API answers 429 Too Many Requests, often with a Retry-After header saying how many seconds to wait. Some APIs also send headers on every reply telling you how much of your allowance remains.


The polite response has three parts. Honour Retry-After if it is present. If it is not, back off exponentially: wait one second, then two, then four, then eight. Add a little randomness so that several scripts do not all retry at the same instant. Give up after a handful of attempts rather than trying forever. And design the script so it rarely hits the limit in the first place. Pull once and reuse the result, ask for big pages, and filter on the server so you fetch only what you need.


import time, random

def get_with_backoff(url, headers, attempts=5):
    for n in range(attempts):
        resp = requests.get(url, headers=headers, timeout=30)
        if resp.status_code != 429:
            resp.raise_for_status()
            return resp
        wait = float(resp.headers.get("Retry-After", 2 ** n)) + random.random()
        time.sleep(wait)
    raise RuntimeError("rate limited too many times: " + url)

That function is a dozen lines and you can paste it into every read script you ever write. It is the difference between a script that quietly copes with a busy server and one that fails on the first 429. Worse, the script without it can hammer the server until someone notices the console has become sluggish and starts hunting for the cause.


Tip: the person most likely to be hurt by your script's rate is you. If the console feels slow at the exact minute your sync runs, you have found the cause. Spread scheduled pulls across the hour rather than starting everything at the top of it, and never poll faster than the data actually changes.


Filter on the server, and cache what does not change


The lazy way to find open critical alerts is to fetch every alert the system has ever recorded and sift through them locally. It works in the lab and falls over in production, where the history runs to hundreds of thousands of rows. The right way is to let the API do the narrowing, through query parameters:


# only what you need
/api/alerts?state=open&severity=critical
/api/devices?type=switch&tag=core
/api/alerts?since=<timestamp>                 # only what changed since last run
/api/devices?fields=id,name,address,status  # only the columns you use

Server-side filtering means less data over the wire, less parsing on your side, fewer pages, and fewer requests against the rate limit. The since style is the most valuable one. A script that remembers when it last ran and asks only for changes since then can run every minute. At that pace, it never fetches more than a handful of rows. Be especially careful with metric history endpoints, which return a data point per interval per device. Ask for a narrow time range and a small set of devices, or you will be surprised by the size of the answer.


Cache what does not change

The device list changes a few times a week. Alert state changes every few minutes. Metric values change every poll. Match how often you fetch each to how often it moves. And keep the last result on disk so that other scripts, and your own next run, can reuse it. Here is a simple pattern. The sync job writes devices.json once an hour. The dashboard, the report, and the pre-deployment check all read that file rather than each asking the API separately. The API sees one request an hour instead of dozens. If the monitor is briefly unavailable, the consumers still have a slightly stale answer rather than none.


Some APIs support conditional requests. You send back an identifier from the last reply (an ETag header or a last-modified time). The server answers "nothing changed" in a tiny reply if that is true. If your product offers it, it is the cheapest request there is. Either way, always record when a cached result was fetched, and have consumers treat a stale cache as a warning rather than silently trusting it forever.


Handling errors and timeouts


A read script fails in one of four ways, and each deserves a different reaction.


What happenedWhat you seeWhat the script should do
You asked wrong400, 404, or a JSON error bodyStop. Log the URL and the body. This is a bug in the script; retrying will not help.
The token is wrong or under-privileged401 or 403Stop and alert a human. Do not retry: repeated failures may lock the account.
The server is busy or down429, 500, 502, 503, or a connection refusedBack off and retry a few times, then fail loudly.
The server is slow or the network is flakyA timeout with no status code at allRetry once or twice with the same timeout; then fail loudly.

"Fail loudly" means the script exits with a non-zero code and writes a clear line to a log with the time and the reason. It does not leave a half-written output file behind that a downstream consumer might mistake for a complete one. Write to a temporary file and rename it into place only on success. A timeout is not optional: without one, a script waiting on a hung server sits forever. And its scheduled task never runs again because the previous instance is still "running." Thirty seconds is a reasonable default for a single request; adjust for endpoints you know to be slow.


Finally, a read script that never runs is indistinguishable from one that runs perfectly if nobody checks. Have the script write a small "last successful run" marker, and have something watch that marker's age. The guide on gluing systems together shows the heartbeat pattern that makes silent failure visible.


Getting it out and running it on a schedule


CSV and JSON

Once the data is in your script, it needs to leave in a shape the next consumer can use. Two formats cover almost everything. JSON is right when the consumer is another script or a web page: write it out exactly as received, or trimmed to the fields you need. CSV (comma-separated values, the universal spreadsheet format) is right when a human will open it. The only wrinkle is that JSON nests and CSV does not. A device whose tags field is a list needs that list flattened into one cell.


# PowerShell: flatten the tags list, then export
$all | Select-Object id, name, address, type, status,
        @{ n = "tags"; e = { $_.tags -join ";" } } |
    Export-Csv -Path "C:\reports\devices.csv" -NoTypeInformation -Encoding UTF8

# Python: the same idea with the csv module
import csv
with open("devices.csv", "w", newline="", encoding="utf-8") as f:
    w = csv.writer(f)
    w.writerow(["id", "name", "address", "type", "status", "tags"])
    for d in devices:
        w.writerow([d["id"], d["name"], d["address"], d["type"],
                    d["status"], ";".join(d.get("tags", []))])

Small courtesies matter here. Write a header row. Use UTF-8 so that device names with accents survive. Put a timestamp in the filename or the first line so nobody mistakes last month's export for today's. And if the CSV is going to a spreadsheet user, sort it the way they will want to read it. That is because they will not know how to sort it themselves and will ask you.


Scheduling the pull

A script you run by hand is a demo. A script that runs itself is an integration. On Windows, Task Scheduler runs a PowerShell script on any schedule you like; on Linux, cron does the same for shell or Python. The checklist that separates a reliable scheduled pull from one that mysteriously stops after a month:


  • Run it as a dedicated service account, not your own login, so it survives your password change and your holiday.
  • Give that account read access to the token file and write access to the output folder, and nothing else.
  • Redirect the script's output to a log file with the date in its name, and rotate or delete old logs.
  • Configure the task to stop the job if it runs longer than a sensible limit, and not to start a new instance while one is running.
  • Write a "last success" marker at the end of a good run, and watch its age.
  • Keep the script in version control with a short README saying what it reads, where it writes, and which token it uses.

Pick an interval by asking how stale the output may be before someone cares. An inventory sync is happy nightly. A dashboard feed wants a minute or two. A pre-deployment alert check runs on demand, when the deployment starts, and is not scheduled at all.


Patterns, examples, and gotchas


PatternExampleGotcha
Nightly inventory syncPull all devices, write CSV and JSON, hand to the CMDB importPagination: the first page is not the whole list. Loop until next is empty.
Alert snapshot for a dashboardEvery minute, pull open alerts, write a small JSON file the page readsRate limits: one request per minute is fine; one per second is not. Cache between runs.
Change-only pullRemember the last run time; ask for ?since= that timeClock skew between your host and the monitor can miss or duplicate rows; overlap the window by a minute.
Pre-deployment interlockBefore deploying, fetch open critical alerts for the target devices; abort if anyA failed API call must abort the deployment too, not be treated as "no alerts."
Availability reportPull alert history for a month, compute downtime per deviceHistory endpoints are heavy; narrow the time range and device set, and expect many pages.
Metric exportPull interface utilization for a handful of uplinksUnits and intervals vary; read the documentation before assuming bits versus bytes.
Any of the above—No timeout, no status check, token in the script file. Fix all three before scheduling.

Where to go next


You now have the whole read side. A GET with a token brings the data in; pagination brings all of it. Server-side filters bring only what you need. A cache keeps you from asking twice; backoff keeps you polite. Timeouts and status checks keep you honest. CSV or JSON carries the result to whoever needs it. A scheduled task with a log and a heartbeat makes it an integration rather than a demo. None of it requires a developer, and all of it is worth more than the ritual of copy and paste it replaces.


The other direction, sending events into the monitor, is covered in pushing events in. Connecting what you pull to tickets, chat, and remediation is the subject of gluing systems together. The care of the tokens these scripts carry is in API security and hygiene. All of them live under Monitoring APIs and Webhooks.


Put this into practice with SysPeep Monitor

If what you really want is the device list and the alert history in a form you can hand to someone, start with what the monitor already produces. SysPeep Monitor generates reports and dashboards from its web console and sends every alert by email and other notifications. Those reports and alerts are its integration surface; check the product documentation for what else is exposed. The free trial lets you see what its discovery and SNMP, WMI, and SSH collection produce before you write a line of script.

Download Free TrialLearn About SysPeep