Bluebot Developer Center
  • Getting Started
  • Introduction
  • Authentication
  • REST API
  • Organizations
  • Devices
  • Device Data
  • Historical (Flow)
  • Realtime (MQTT)
  • Resources
  • Using openapi-typescript
  • API Playground (Swagger)↗
  • OpenAPI/Swagger JSON↗

Historical Data (Flow)

The flow endpoints serve historical device readings — either at native resolution (raw) or pre-aggregated into 1-minute, 5-minute, 10-minute, or 1-hour buckets. Across all flow endpoints, the {id} path parameter accepts a UUID, a serial number, or a network unique identifier.

Each example below is runnable. Set your API key (and optionally a default device id) in the header, click an example to expand, tweak parameters, and hit Send Request.

Beta: these endpoints are in beta and may change based on customer feedback.

Datapoints

GET /flow/datapoints/{id} returns datapoints (or aggregations) for one device. Use resolution to switch between raw rows, pre-aggregated views (1min/5min/10min/1hour), per-day or per-month rollups (day/month), or a single whole-range total (total).

Last hour, 5-minute bucketsGET/flow/datapoints/{id}View example ↗

Quick-look query for one device over the past hour using the 5-minute aggregate view.

Path parameters

NameValueDescription
id*
string
Device identifier — UUID, serial number, or networkUniqueIdentifier.

Query parameters

NameValueDescription
resolution*
raw | 1min | 5min | 10min | 1hour | day | month | total
Bucket size.
from
string (ISO 8601)
Inclusive lower bound.
to
string (ISO 8601)
Inclusive upper bound.
limit
number
Page size. Max 10000.

Request

bash
curl "https://prod.bluebot.com/management/v1/flow/datapoints/{id}?resolution=5min&from=2026-05-10T04%3A51%3A30Z&to=2026-05-10T05%3A51%3A30Z&limit=100" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "bluebot-api-key: YOUR_API_KEY"
Set an API key in the header to try this request.

Example response

json
{
  "resolution": "5min",
  "timezone": null,
  "limit": 100,
  "offset": 0,
  "data": [
    {
      "bucket_5min": "2026-05-02T16:00:00Z",
      "avg_flow_rate": 2.48,
      "min_flow_rate": 0,
      "max_flow_rate": 5.1,
      "total_flow_amount": 12.4,
      "avg_quality": 1.0,
      "min_quality": 0.99,
      "max_quality": 1.0
    }
  ]
}
Raw readings, last 5 minutesGET/flow/datapoints/{id}View example ↗

Native-resolution rows from thin.device_datapoints — useful for debugging individual readings.

Path parameters

NameValueDescription
id*
string
Device identifier — UUID, serial number, or networkUniqueIdentifier.

Query parameters

NameValueDescription
resolution*
raw | 1min | 5min | 10min | 1hour | day | month | total
Bucket size.
from
string (ISO 8601)
Inclusive lower bound.
to
string (ISO 8601)
Inclusive upper bound.
limit
number
Page size. Max 10000.

Request

bash
curl "https://prod.bluebot.com/management/v1/flow/datapoints/{id}?resolution=raw&from=2026-05-10T05%3A46%3A30Z&to=2026-05-10T05%3A51%3A30Z&limit=200" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "bluebot-api-key: YOUR_API_KEY"
Set an API key in the header to try this request.

Example response

json
{
  "resolution": "raw",
  "timezone": null,
  "limit": 200,
  "offset": 0,
  "data": [
    {
      "recorded_at": "2026-05-02T16:54:31Z",
      "flow_rate": 2.48,
      "flow_duration": 5.0,
      "flow_amount": 0.21,
      "quality": 1.0,
      "signal_strength": -67,
      "network_rssi": -82,
      "onboard_temperature": 22.4
    }
  ]
}
Today's flow total in your timezoneGET/flow/datapoints/{id}View example ↗

Use resolution=total to collapse the matched range into a single row of aggregates. Pair with from=start-of-today (in your IANA zone) and to=now to get a running today's-total.

Path parameters

NameValueDescription
id*
string
Device identifier — UUID, serial number, or networkUniqueIdentifier.

Query parameters

NameValueDescription
resolution*
raw | 1min | 5min | 10min | 1hour | day | month | total
Bucket size.
from
string (ISO 8601)
Inclusive lower bound — start of today in your timezone.
to
string (ISO 8601)
Inclusive upper bound — now.
timezone
string (IANA)
IANA zone for any returned timestamps.

Request

bash
curl "https://prod.bluebot.com/management/v1/flow/datapoints/{id}?resolution=total&from=2026-05-09T00%3A00%3A00-07%3A00&to=2026-05-10T05%3A51%3A30Z&timezone=America%2FLos_Angeles" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "bluebot-api-key: YOUR_API_KEY"
Set an API key in the header to try this request.

Example response

json
{
  "resolution": "total",
  "timezone": "America/Los_Angeles",
  "limit": 1,
  "offset": 0,
  "data": [
    {
      "total_flow_amount": 27.4,
      "avg_flow_rate": 1.85,
      "min_flow_rate": 0,
      "max_flow_rate": 4.2,
      "avg_quality": 1.0,
      "min_quality": 0.99,
      "max_quality": 1.0
    }
  ]
}
Daily flow totals for the past 30 daysGET/flow/datapoints/{id}View example ↗

Use resolution=day to get one row per local day in the timezone you specify — replaces the previous sum=true, group=day combo.

Path parameters

NameValueDescription
id*
string
Device identifier — UUID, serial number, or networkUniqueIdentifier.

Query parameters

NameValueDescription
resolution*
raw | 1min | 5min | 10min | 1hour | day | month | total
Bucket size.
from
string (ISO 8601)
Inclusive lower bound.
to
string (ISO 8601)
Inclusive upper bound.
timezone
string (IANA)
Aligns day boundaries to this zone.

Request

bash
curl "https://prod.bluebot.com/management/v1/flow/datapoints/{id}?resolution=day&from=2026-04-10T05%3A51%3A30Z&to=2026-05-10T05%3A51%3A30Z&timezone=America%2FLos_Angeles" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "bluebot-api-key: YOUR_API_KEY"
Set an API key in the header to try this request.

Example response

json
{
  "resolution": "day",
  "timezone": "America/Los_Angeles",
  "limit": 100,
  "offset": 0,
  "data": [
    {
      "bucket": "2026-04-07T00:00:00-07:00",
      "total_flow_amount": 184.6,
      "avg_flow_rate": 1.92,
      "min_flow_rate": 0,
      "max_flow_rate": 6.4
    }
  ]
}
Just the row countGET/flow/datapoints/{id}View example ↗

Skip the data and return only how many rows match. Useful for sizing a follow-up query.

Path parameters

NameValueDescription
id*
string
Device identifier — UUID, serial number, or networkUniqueIdentifier.

Query parameters

NameValueDescription
resolution*
raw | 1min | 5min | 10min | 1hour | day | month | total
Bucket size.
from
string (ISO 8601)
Inclusive lower bound.
to
string (ISO 8601)
Inclusive upper bound.
count
boolean
Return only { resolution, count }.

Request

bash
curl "https://prod.bluebot.com/management/v1/flow/datapoints/{id}?resolution=raw&from=2026-05-09T05%3A51%3A30Z&to=2026-05-10T05%3A51%3A30Z&count=true" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "bluebot-api-key: YOUR_API_KEY"
Set an API key in the header to try this request.

Example response

json
{
  "resolution": "raw",
  "count": 4218
}

Adaptive

GET /flow/adaptive/{id} walks raw → 1min → 5min → 10min → 1hour and returns data at the finest resolution whose row count fits within maxDatapoints. Best for charting variable time ranges.

Last 24 hours, ~500 datapointsGET/flow/adaptive/{id}View example ↗

Good default for a one-day chart.

Path parameters

NameValueDescription
id*
string
Device identifier — UUID, serial number, or networkUniqueIdentifier.

Query parameters

NameValueDescription
from*
string (ISO 8601)
Inclusive lower bound.
to*
string (ISO 8601)
Inclusive upper bound.
maxDatapoints
number
Cap the returned row count.

Request

bash
curl "https://prod.bluebot.com/management/v1/flow/adaptive/{id}?from=2026-05-09T05%3A51%3A30Z&to=2026-05-10T05%3A51%3A30Z&maxDatapoints=500" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "bluebot-api-key: YOUR_API_KEY"
Set an API key in the header to try this request.

Example response

json
{
  "resolution": "5min",
  "count": 288,
  "truncated": false,
  "timezone": null,
  "data": [
    {
      "bucket_5min": "2026-05-01T17:00:00Z",
      "avg_flow_rate": 2.48,
      "total_flow_amount": 24.1
    }
  ]
}
Last 7 days, ~1000 datapointsGET/flow/adaptive/{id}View example ↗

Wider range with a larger budget — typically returns 10-min or 1-hour resolution.

Path parameters

NameValueDescription
id*
string
Device identifier — UUID, serial number, or networkUniqueIdentifier.

Query parameters

NameValueDescription
from*
string (ISO 8601)
Inclusive lower bound.
to*
string (ISO 8601)
Inclusive upper bound.
maxDatapoints
number
Cap the returned row count.

Request

bash
curl "https://prod.bluebot.com/management/v1/flow/adaptive/{id}?from=2026-05-03T05%3A51%3A30Z&to=2026-05-10T05%3A51%3A30Z&maxDatapoints=1000" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "bluebot-api-key: YOUR_API_KEY"
Set an API key in the header to try this request.

Example response

json
{
  "resolution": "10min",
  "count": 1008,
  "truncated": false,
  "timezone": null,
  "data": [
    {
      "bucket_10min": "2026-04-29T00:00:00Z",
      "avg_flow_rate": 1.85,
      "total_flow_amount": 18.5
    }
  ]
}
Last 30 days, in your timezoneGET/flow/adaptive/{id}View example ↗

Returns bucket timestamps as wall-clock time in the given IANA zone, useful for date-aligned charts.

Path parameters

NameValueDescription
id*
string
Device identifier — UUID, serial number, or networkUniqueIdentifier.

Query parameters

NameValueDescription
from*
string (ISO 8601)
Inclusive lower bound.
to*
string (ISO 8601)
Inclusive upper bound.
maxDatapoints
number
Cap the returned row count.
timezone
string (IANA)
Wall-clock zone for bucket timestamps.

Request

bash
curl "https://prod.bluebot.com/management/v1/flow/adaptive/{id}?from=2026-04-10T05%3A51%3A30Z&to=2026-05-10T05%3A51%3A30Z&maxDatapoints=1000&timezone=America%2FLos_Angeles" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "bluebot-api-key: YOUR_API_KEY"
Set an API key in the header to try this request.

Example response

json
{
  "resolution": "1hour",
  "count": 720,
  "truncated": false,
  "timezone": "America/Los_Angeles",
  "data": [
    {
      "bucket_1hour": "2026-04-06T00:00:00-07:00",
      "avg_flow_rate": 1.92,
      "total_flow_amount": 7.7
    }
  ]
}

Latest

GET /flow/latest returns latest summary metrics across up to 50 devices in one call — good for status overviews and dashboards.

All metrics for one deviceGET/flow/latestView example ↗

Uptime, last-seen, and quality computed over the default 24-hour window.

Query parameters

NameValueDescription
ids*
string (comma-separated)
One or more device identifiers (UUIDs, serials, or NUIDs).
metrics*
uptime,lastSeen,quality
Comma-separated subset of metrics.

Request

bash
curl "https://prod.bluebot.com/management/v1/flow/latest?metrics=uptime%2ClastSeen%2Cquality" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "bluebot-api-key: YOUR_API_KEY"
Set an API key in the header to try this request.

Example response

json
{
  "range": { "from": "2026-05-01T17:00:00Z", "to": "2026-05-02T17:00:00Z" },
  "qualityResolution": "1hour",
  "uptimeResolution": "1min",
  "expectedBuckets": 1440,
  "data": [
    {
      "deviceId": "5f8b1f6e-4c2a-4d3b-9a3f-8b1c2d4e5f6a",
      "serialNumber": "BB-000123",
      "networkUniqueIdentifier": "0004A30B001D2E3F",
      "lastSeen": "2026-05-02T17:12:08Z",
      "uptime": { "actual": 1437, "expected": 1440 },
      "quality": { "min": 0.98, "max": 1.0 }
    }
  ]
}
Just last-seen across multiple devicesGET/flow/latestView example ↗

Cheapest way to ask 'is each of these devices alive?' Pass up to 50 ids, comma-separated.

Query parameters

NameValueDescription
ids*
string (comma-separated)
Comma-separated list of up to 50 device identifiers.
metrics*
uptime,lastSeen,quality
Comma-separated subset of metrics.

Request

bash
curl "https://prod.bluebot.com/management/v1/flow/latest?metrics=lastSeen" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "bluebot-api-key: YOUR_API_KEY"
Set an API key in the header to try this request.

Example response

json
{
  "range": { "from": "2026-05-01T17:00:00Z", "to": "2026-05-02T17:00:00Z" },
  "qualityResolution": null,
  "uptimeResolution": null,
  "expectedBuckets": 0,
  "data": [
    {
      "deviceId": "5f8b1f6e-4c2a-4d3b-9a3f-8b1c2d4e5f6a",
      "serialNumber": "BB-000123",
      "networkUniqueIdentifier": "0004A30B001D2E3F",
      "lastSeen": "2026-05-02T17:12:08Z"
    },
    {
      "deviceId": "9c2d8a31-7e4f-41a9-b2c5-3d6e8f1a2b4c",
      "serialNumber": "BB-000124",
      "networkUniqueIdentifier": "0004A30B001D2E40",
      "lastSeen": "2026-05-02T17:11:54Z"
    }
  ]
}
Uptime over the past hourGET/flow/latestView example ↗

Override the default 24-hour window to compute uptime on a tighter range with sub-minute resolution.

Query parameters

NameValueDescription
ids*
string (comma-separated)
Up to 50 device identifiers, comma-separated.
metrics*
uptime,lastSeen,quality
Comma-separated subset of metrics.
from
string (ISO 8601)
Lower bound for the metric window.
to
string (ISO 8601)
Upper bound for the metric window.
uptimeResolution
1min | 5min | 10min | 1hour
Resolution used to count expected buckets.

Request

bash
curl "https://prod.bluebot.com/management/v1/flow/latest?metrics=uptime&from=2026-05-10T04%3A51%3A30Z&to=2026-05-10T05%3A51%3A30Z&uptimeResolution=1min" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "bluebot-api-key: YOUR_API_KEY"
Set an API key in the header to try this request.

Example response

json
{
  "range": { "from": "2026-05-02T16:00:00Z", "to": "2026-05-02T17:00:00Z" },
  "qualityResolution": null,
  "uptimeResolution": "1min",
  "expectedBuckets": 60,
  "data": [
    {
      "deviceId": "5f8b1f6e-4c2a-4d3b-9a3f-8b1c2d4e5f6a",
      "serialNumber": "BB-000123",
      "networkUniqueIdentifier": "0004A30B001D2E3F",
      "uptime": { "actual": 60, "expected": 60 }
    }
  ]
}
  • On this page
  • Datapoints
    • Last hour, 5-minute buckets
    • Raw readings, last 5 minutes
    • Today's flow total in your timezone
    • Daily flow totals for the past 30 days
    • Just the row count
  • Adaptive
    • Last 24 hours, ~500 datapoints
    • Last 7 days, ~1000 datapoints
    • Last 30 days, in your timezone
  • Latest
    • All metrics for one device
    • Just last-seen across multiple devices
    • Uptime over the past hour