# 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](#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`](https://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](#bulk-export-a-whole-dataset-as-one-file).

## 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:

```python
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](#cursor-pagination) for why there's no row count:

```python
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](#bulk-export-a-whole-dataset-as-one-file) 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](#prefer-a-client-library-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](#odata-details-filtering-and-sorting) 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:

```bash
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:

```python
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:

```bash
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](pushing-data.md)). 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:

```python
# 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:

```python
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`):

```python
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:

```python
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:

```json
{
  "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](../measurements.md#a-single-readings-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:

```bash
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`](https://app.mechbase.io/api/docs) |
| Python / Go / Swift / Kotlin SDK | `pip install mechbase` · [github.com/arpedon/mechbase-sdk](https://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](https://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) |
