Mechbase Manual

15 · 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:

  1. Live feeds — paged JSON or CSV you walk page by page (good for a sync job or a quick pull).

  2. 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).

  3. 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 see app.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 mechbase command-line tool (it comes with the Python SDK — pipx install mechbase): run mechbase 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 is POST /api/auth/token with your email as username, your password, and a device_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.

  1. Power BI: Get Data → OData feed. Excel: Data → Get Data → From Other Sources → From OData Feed.

  2. Paste the OData root for your installation:

    https://app.mechbase.io/api/installations/<INSTALLATION_ID>/analytics/odata/
    
  3. When prompted for credentials, choose Web API / API key and set the key to:

    Bearer <TOKEN>
    

    (Include the word Bearer and a space before the token — it’s the same Authorization header value as everywhere else.)

  4. 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=csv

  • Parser: 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_cursor from each response and pass it back as ?cursor=.... When next_cursor is null, 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_uuid

    • events → event_id

    • inspections → 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_since with a created_from/created_to window 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. Leave created_* 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

asset_id, asset_external_id, point_id, point_external_id, transducer_type, status (good|elevated|minor|major)

events

action

inspections

route_id (the route’s UUID), status (good|elevated|minor|major)

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_url signature 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 — comparisons eq / ge / le / gt / lt, joined with and, over the per-set fields below.

  • $select — pick columns.

  • $orderby — only on the time axes: timestamp (when it happened) or synced_at (when it was last updated; Measurements and Inspections only — Events order by timestamp), asc or desc. Any other field returns 501 (sorting on other columns would break paging).

  • $top — a total row cap across all pages (a strict $top=10 gives 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

measurement_uuid, asset_id, asset_external_id, point_id, point_external_id, transducer_type, status, timestamp, synced_at

Events

event_id, action, timestamp

Inspections

response_uuid, route_id, status, timestamp, synced_at

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

status

Severity label: good, elevated, minor, major. (Note: elevated exists — don’t hardcode just the other three.)

severity_zone

The ISO/alarm zone the reading fell in (may be empty).

metric_key

What the measured value represents (e.g. the metric/channel name).

value

The numeric reading (may be empty for non-numeric rows).

unit

Unit of value.

data

A JSON bag of extra per-row fields that don’t have a dedicated column.

*_uuid / event_id

Stable row identity — dedupe on this in your warehouse.

timestamp

When the reading/event happened.

synced_at

When the row was last updated in Mechbase (the incremental watermark). Measurements and inspections only — events never change, so their watermark is timestamp.

point_sequence

A measurement’s number on its point — the number in the reading’s web address (…/measurements/766/).

transducer_type

The point type code: VB vibration, US ultrasound, TM temperature, IR thermography, PS pressure, FL flow, BL boolean, EI current, EV voltage, TC tachometer, CT counter, ST state, PR production.

*_external_id

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

https://app.mechbase.io/api/installations/<INSTALLATION_ID>/analytics/

Auth header

Authorization: Bearer <TOKEN>

API reference

app.mechbase.io/api/docs

Python / Go / Swift / Kotlin SDK

pip install mechbase · github.com/arpedon/mechbase-sdk

Command-line tool

pipx install mechbase → mechbase login

Dates in filters

ISO 8601 with a time zone (…Z or +02:00) — a date without one is rejected with 422

Raw .dr files

pip install dr-files · pypi.org/project/dr-files

Feed page size

200 rows

End of feed

next_cursor is null

Dedupe keys

measurement_uuid / event_id / response_uuid

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

.../analytics/odata/ (sets: Measurements, Events, Inspections)

Markdown · PDF · Updated 16 Nov 2026