Analytics & BI#
Pulling Mechbase data into pandas, Power BI, Excel, and Grafana.
Get your installation’s measurements, events, and inspection data out of Mechbase
and into the tool you already use. This chapter is written for a data analyst —
someone comfortable with spreadsheets, SQL, or a notebook, but not necessarily a
programmer. Every recipe is copy-paste; replace the <PLACEHOLDERS>.
If you only read one section, read Connect recipes — that covers the 80%.
The one-paragraph version#
Mechbase exposes your data three ways, all read-only:
Live feeds — paged JSON or CSV you walk page by page (good for a sync job or a quick pull).
Bulk export — you ask for a whole dataset as one CSV or Parquet file and download it from a link (good for a full load into a warehouse or notebook).
OData feed — the same data behind a single URL you paste into Power BI or Excel; the tool does the paging for you (the friendliest option if you live in Power BI / Excel).
Everything is scoped to one installation and needs an API token (except the bulk-export download link, which carries its own signature). Pick the recipe for your tool below.
The full API reference. This chapter is a cookbook for the common jobs. For the complete, always-current list of endpoints, parameters, and response shapes, browse the interactive API docs at
app.mechbase.io/api/docs(a self-hosted Mechbase serves them at<your-host>/api/docs).
Before you start: two things you need#
1. Your installation ID#
Every URL contains your installation’s numeric ID. You can read it from the
address bar while using Mechbase — it’s the number straight after the host
(app.mechbase.io/2012/ → 2012) — or ask an administrator. Throughout this chapter it’s written <INSTALLATION_ID>.
The base URL for everything in this chapter is:
https://app.mechbase.io/api/installations/<INSTALLATION_ID>/analytics/
Note: examples use the hosted service at
app.mechbase.io. A self-hosted Mechbase uses its own host — swap it in wherever you seeapp.mechbase.io.
2. An API token#
There are two ways to get one:
Ask an administrator. They create an API Token for you in the admin area (API Tokens → Add), scoped to your user and your installation — or a service token for an unattended integration. They hand you a string that looks like
xK3f....Mint your own with the
mechbasecommand-line tool (it comes with the Python SDK —pipx install mechbase): runmechbase login, enter your email and password, and the token is stored in~/.config/mechbase/config.json. A token you mint yourself works for every installation you belong to. (Under the hood this isPOST /api/auth/tokenwith your email asusername, your password, and adevice_id.)
Either way, treat the token like a password.
You send it on every request as a header:
Authorization: Bearer <TOKEN>
One exception: the bulk-export download link is pre-signed — the signature in the URL is the authorization.
pandas.read_csv(url)or a browser download works with no header. More on that in Bulk export.
Live feed vs bulk export: which do I use?#
You want to… |
Use |
|---|---|
Pull the latest data into a notebook or a sync job, page by page |
Live feed |
Load an entire dataset (millions of rows) into a warehouse or file |
Bulk export |
Point Power BI / Excel at a URL and let it refresh |
OData feed |
Keep a warehouse table in sync with only what changed |
Live feed, incremental mode |
The three feeds and the export cover the same three datasets:
measurements — one row per measurement reading.
events — alarm/audit events.
inspections — route inspection responses (walkthroughs).
Connect recipes#
Python / pandas#
Quick pull of the current page (CSV) — add ?format=csv and pandas reads it
directly. You still send the token:
import pandas as pd
import requests
BASE = "https://app.mechbase.io/api/installations/<INSTALLATION_ID>/analytics"
HEADERS = {"Authorization": "Bearer <TOKEN>"}
# One page (up to 200 rows) of measurements as a DataFrame
r = requests.get(f"{BASE}/measurements/", headers=HEADERS, params={"format": "csv"})
r.raise_for_status()
from io import StringIO
df = pd.read_csv(StringIO(r.text))
Walk every page (JSON) — follow next_cursor until it comes back null.
See Cursor pagination for why there’s no row count:
def pull_all(dataset, **filters):
rows, cursor = [], None
while True:
params = {"cursor": cursor, **filters} if cursor else filters
page = requests.get(f"{BASE}/{dataset}/", headers=HEADERS, params=params).json()
rows.extend(page["items"])
cursor = page["next_cursor"]
if cursor is None: # null cursor = last page
break
return pd.DataFrame(rows)
df = pull_all("measurements", status="major") # only 'major' rows
Big load — for a full dataset, don’t page the live feed; use a
bulk export and pd.read_parquet()
the signed link.
Tip: the analytics feeds are plain HTTP on purpose — the recipe above is all you need. The Mechbase SDK is for the operational API (readings, registry, routes), not these feeds.
Power BI / Excel (the OData feed)#
This is the recommended path for Power BI and Excel — paste one URL and the tool handles the rest.
Power BI: Get Data → OData feed. Excel: Data → Get Data → From Other Sources → From OData Feed.
Paste the OData root for your installation:
https://app.mechbase.io/api/installations/<INSTALLATION_ID>/analytics/odata/
When prompted for credentials, choose Web API / API key and set the key to:
Bearer <TOKEN>
(Include the word
Bearerand a space before the token — it’s the sameAuthorizationheader value as everywhere else.)You’ll see three tables — Measurements, Events, Inspections. Pick one, Load, and refresh whenever you like. The connector walks all the pages for you.
See OData details for filtering and sorting in the query.
Grafana#
Use the Infinity data source (it reads JSON/CSV over HTTP).
URL: a feed endpoint, e.g.
https://app.mechbase.io/api/installations/<INSTALLATION_ID>/analytics/measurements/?format=csvParser: CSV (or JSON — then set the Rows / Root to
items).Headers: add
Authorization=Bearer <TOKEN>.
Infinity pulls one page (200 rows). For dashboards over large ranges, point Grafana at a warehouse table you’ve loaded from a bulk export instead.
Prefer a client library? The Mechbase SDK#
The recipes above talk to the analytics feeds by hand with requests, and that’s
the intended way: the SDK doesn’t wrap the feeds, bulk export, or OData. What the
Mechbase SDK gives you is a typed client for the operational API — reading
assets, points, and individual readings, fetching a reading’s spectra, writing
readings, syncing the registry, and driving routes. It’s available for Python,
Go, Swift, and Kotlin (https://github.com/arpedon/mechbase-sdk).
Install the Python client:
pip install mechbase
It uses the same Bearer token as everything else in this chapter and defaults
to the hosted service — pass a base_url for a self-hosted installation:
from mechbase import Mechbase
client = Mechbase(token="<TOKEN>") # base_url="https://your-host" if self-hosted
inst = client.for_installation(<INSTALLATION_ID>)
# one reading by the number in its web URL (…/measurementpoints/42/measurements/766/)
m = inst.measurements.get(42, 766)
spectra = inst.measurements.spectra(m.uuid) # same arrays as the Spectra section below
# push a reading (the SDK also syncs the registry by external ID and drives routes)
inst.measurements.create(point_id=42, data={"rms": 2.3}, notes="manual reading")
The Python package also installs the mechbase command-line tool, handy for a
quick look without writing code:
mechbase login # once; stores a token
mechbase use 2012 # pick the installation
mechbase points -q "motor" # find points
mechbase readings 42 -n 5 # latest readings on point 42
mechbase reading show 42 766 --peaks 10 # values, state, and the top spectrum peaks
Add --json to any command for machine-readable output.
For the read-only analytics feeds in this chapter, the copy-paste recipes above are the shortest path. Reach for the SDK when you’re building an integration that also writes back to Mechbase — bulk measurement uploads, registry sync, or an edge agent (Pushing data into Mechbase). See the repository README for the full surface.
Cursor pagination#
The feeds page with a cursor, not page numbers, and they deliberately do not return a total row count (counting millions of rows on every request is slow). The rule is simple:
Read
next_cursorfrom each response and pass it back as?cursor=.... Whennext_cursorisnull, you’ve reached the end.
Each page holds up to 200 rows. There’s no “page 5 of 100” — just keep
walking until the cursor is null. A cursor is tied to the mode and dataset it
was minted for; don’t reuse a measurements cursor on the events feed (you’ll get
a clean 422, not wrong rows).
Incremental sync (only what changed)#
To keep a warehouse table fresh without re-downloading everything, use
incremental mode: pass ?updated_since=<ISO-8601 timestamp>.
The feed switches to oldest-changed-first, walking a “last updated” watermark. A reading that was backdated or re-finalized after your last run is re-emitted, so you never miss an edit.
The feed is at-least-once — the same row can appear twice across runs. Dedupe in your warehouse by upserting on the row’s UUID column:
measurements →
measurement_uuidevents →
event_idinspections →
response_uuid
Recipe:
# Save this from the last successful run (start with a far-past date the
# first time), then pass it next time.
last_run = "2026-06-01T00:00:00Z"
df = pull_all("measurements", updated_since=last_run)
# ... upsert df into your warehouse on measurement_uuid ...
# then store "now" as the next last_run
Gotcha: don’t combine
updated_sincewith acreated_from/created_towindow for a changed-since sync. The created window also constrains incremental pulls, so a late-edited row whose reading time falls outside the window won’t re-emit. Leavecreated_*unset for a complete sync.
Filtering#
All feeds accept a created_from / created_to window (ISO-8601) on the
measurement/event time. Beyond that, each dataset has its own filters:
Dataset |
Filters |
|---|---|
measurements |
|
events |
|
inspections |
|
Example: major-severity readings on one asset in May:
.../analytics/measurements/?asset_id=42&status=major&created_from=2026-05-01T00:00:00Z&created_to=2026-06-01T00:00:00Z
Bulk export (a whole dataset as one file)#
For a full load, ask Mechbase to build one file. It’s a three-step flow:
1. Start the job (POST). Body picks the dataset, the format, and the same filters as the live feed:
job = requests.post(f"{BASE}/exports/", headers=HEADERS, json={
"dataset": "measurements", # measurements | events | inspections
"format": "parquet", # parquet | csv
"filters": {"status": "major"} # same filters as the feeds (optional)
}).json()
status_url = job["status_url"]
2. Poll until it’s done. The status response reports
pending → running → done (or failed / expired):
import time
while True:
s = requests.get(status_url, headers=HEADERS).json()
if s["state"] in ("done", "failed", "expired"):
break
time.sleep(3)
3. Download the signed link. When state is done, the status response
carries a download_url. That link needs no token — the signature in the
URL is the authorization:
import pandas as pd
df = pd.read_parquet(s["download_url"]) # or pd.read_csv for a CSV export
Things to know:
Row caps: a normal (interactive) token can export up to 100,000 rows; a service token is capped at 10,000,000. Ask an administrator for a service token for large warehouse loads.
Link lifetime: the
download_urlsignature is short-lived (~15 minutes). If it expires, just poll the status again — each poll mints a fresh link. The file itself lives for 24 hours after it’s built.Concurrency: up to 3 export jobs can run at once per installation. Beyond that you get a
429— wait for one to finish.
Spectra (FFT arrays for one measurement)#
Every vibration measurement with a stored waveform has spectra — served from a
cache, or computed from the waveform on request. The feed row keeps the heavy
arrays out (it gives you a spectra_url, and spectra_available tells you whether
there’s a waveform behind it); fetch them by URL when you need them:
GET .../analytics/measurements/<MEASUREMENT_UUID>/spectra/
Returns the frequency axis plus the velocity / acceleration / envelope arrays and the unit:
{
"measurement_uuid": "…",
"freq_hz": [0.0, 1.5, 3.0, …],
"velocity": [...],
"acceleration": [...],
"envelope": [...],
"unit": "mm/s",
"source": "cache" // "empty" only when the reading has no waveform
}
Raw signal files (.dr)#
The spectra above are the processed arrays. For the full raw waveform behind
a high-rate reading, download the measurement’s Mechbase data-recorder file
(.dr) — see
A single reading’s page.
To read a .dr file in Python, use the dr-files package, which converts it
into standard formats you can load straight into a notebook:
pip install dr-files
https://pypi.org/project/dr-files/ · https://github.com/arpedon/dr-files
OData details (filtering and sorting)#
The OData feed lives at:
https://app.mechbase.io/api/installations/<INSTALLATION_ID>/analytics/odata/
with three entity sets: Measurements, Events, Inspections. It’s a
read-only subset of OData v4 — enough for Power BI / Excel, not the whole
spec. Supported query options:
$filter— comparisonseq/ge/le/gt/lt, joined withand, over the per-set fields below.$select— pick columns.$orderby— only on the time axes:timestamp(when it happened) orsynced_at(when it was last updated; Measurements and Inspections only — Events order bytimestamp),ascordesc. Any other field returns501(sorting on other columns would break paging).$top— a total row cap across all pages (a strict$top=10gives exactly 10 rows, not a page size).$count=true— adds@odata.count(the full filtered total).
Paging is automatic in Power BI/Excel; if you call OData by hand, follow
@odata.nextLink until it’s absent.
Filterable fields per set:
Set |
Fields |
|---|---|
Measurements |
|
Events |
|
Inspections |
|
Example — major readings since May, newest first, just two columns:
.../analytics/odata/Measurements?$filter=status eq 'major' and timestamp ge 2026-05-01T00:00:00Z&$orderby=timestamp desc&$select=measurement_uuid,value
There’s also a service document (/odata/) listing the sets and a $metadata
document (/odata/$metadata) describing the columns — Power BI reads both
automatically.
Field dictionary#
The columns you’ll meet most often:
Field |
Meaning |
|---|---|
|
Severity label: |
|
The ISO/alarm zone the reading fell in (may be empty). |
|
What the measured value represents (e.g. the metric/channel name). |
|
The numeric reading (may be empty for non-numeric rows). |
|
Unit of |
|
A JSON bag of extra per-row fields that don’t have a dedicated column. |
|
Stable row identity — dedupe on this in your warehouse. |
|
When the reading/event happened. |
|
When the row was last updated in Mechbase (the incremental watermark). Measurements and inspections only — events never change, so their watermark is |
|
A measurement’s number on its point — the number in the reading’s web address ( |
|
The point type code: |
|
Your own external identifiers (asset/point), when set. |
Known limitation: hard-deletes don’t propagate#
If a row is hard-deleted in Mechbase, it does not get announced through the
feeds — incremental sync only ever adds or updates, it never tells you
something disappeared. To stay exactly in sync, do a periodic full refresh
(a full bulk export, or a feed pull with no updated_since) on whatever cadence
your accuracy needs — e.g. nightly or weekly.
Quick reference#
Thing |
Value |
|---|---|
Base URL |
|
Auth header |
|
API reference |
|
Python / Go / Swift / Kotlin SDK |
|
Command-line tool |
|
Dates in filters |
ISO 8601 with a time zone ( |
Raw |
|
Feed page size |
200 rows |
End of feed |
|
Dedupe keys |
|
Export row cap |
100k (interactive) / 10M (service token) |
Export link TTL |
~15 min (re-poll for a fresh one) |
Export file TTL |
24 hours |
Max concurrent exports |
3 per installation |
OData root |
|