Data Readback API

Read your equipment's sensor data from Turbomechanica over HTTPS.

In the URLs below, replace $ORG with your organisation's Turbomechanica subdomain (for example, chevron for chevron.turbomechanica.ai).

1. Create API credentials

1. Sign in to Turbomechanica as an Administrator or Developer.
2. Go to Settings > Service Accounts.
3. Under API credentials, select New credential, enter a name and select Create.
4. Copy the Client ID and Client secret. The secret is shown only once.

From the same page you can Rotate a credential's secret or Delete a credential. The old secret stops working when you rotate.

2. Get an access token

https://$ORG.accounts.turbomechanica.ai/oauth/token (POST)

curl -s -X POST https://$ORG.accounts.turbomechanica.ai/oauth/token \
  -H 'Content-Type: application/json' \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "<CLIENT_ID>",
    "client_secret": "<CLIENT_SECRET>",
    "audience": "https://api.turbomechanica.ai"
  }'

Response:

{
  "access_token": "eyJhbGciOi...",
  "scope": "readback:read",
  "expires_in": 3600,
  "token_type": "Bearer"
}

The token is valid for one hour. Reuse it until it expires, then request a new one.

3. Call the API

Base URL: https://api.$ORG.turbomechanica.ai/external

Send the token on every request:

Authorization: Bearer <access_token>

List equipment

GET /v1/equipments?page=1&page_size=100

{
  "page": 1,
  "page_size": 100,
  "total": 2,
  "equipments": [
    {"id": 3, "name": "LNG Train 3 Expander", "tag": "LNG03-EXP", "sensor_count": 42}
  ]
}

List sensors on an equipment

GET /v1/sensors?equipment_id=3&page=1&page_size=100

{
  "equipment_id": 3,
  "page": 1,
  "page_size": 100,
  "total": 42,
  "sensors": [
    {"id": 3997, "tag": "LNG03-FI_TOTAL", "name": "Liquid Expander Flow", "unit": "gal(US)/min", "category": "physical"}
  ]
}

page_size is at most 1000 for both list calls.

Read data for an equipment

GET /v1/equipments/{equipment_id}/data

curl -s -H "Authorization: Bearer $TOKEN" \
  "https://api.$ORG.turbomechanica.ai/external/v1/equipments/3/data?start_time=2025-06-01T00:00:00Z&end_time=2025-06-01T01:00:00Z"

Read data for specific sensors

GET /v1/sensors/data?sensor_id=3997&sensor_id=3998&start_time=...&end_time=...

sensor_id is repeated once per sensor. The other parameters are the same as above, without sensors.

Data response

{
  "equipment_id": 3,
  "start_time": "2025-06-01T00:00:00Z",
  "end_time": "2025-06-01T01:00:00Z",
  "page": 1,
  "page_size": 60,
  "total_pages": 2,
  "page_window": {"start_time": "2025-06-01T00:00:00Z", "end_time": "2025-06-01T00:30:00Z"},
  "cadence_seconds": 30,
  "snapshot_id": 5685063355100170478,
  "timestamps": ["2025-06-01T00:00:00Z", "2025-06-01T00:00:30Z"],
  "series": {
    "LNG03-FI_TOTAL": [7970.7, 7933.8],
    "LNG03-PI_SUC": [null, 412.1]
  },
  "sensors": {
    "LNG03-FI_TOTAL": {"id": 3997, "name": "Liquid Expander Flow", "unit": "gal(US)/min", "category": "physical"}
  }
}

• timestamps and each array in series have the same length and align by index.
• null means no reading at that timestamp.
• Values are in the unit listed for each tag in sensors.

4. Read a full time window

1. Request page 1.
2. Note total_pages and snapshot_id.
3. Request pages 2 to total_pages with the same parameters, adding page and snapshot_id.
4. For windows longer than 24 hours, repeat for consecutive windows.

Limits

• Window (end_time - start_time): at most 24 hours.
• One page covers at most 1 hour of data.
• page_size × number of sensors: at most 500,000 values. Use sensors or sensor_id to request fewer sensors for larger pages.
• Concurrent data requests are limited. Requests over the limit receive 503; retry after a short delay.

Errors

Python example

import requests

ORG = "chevron"
token = requests.post(
    f"https://{ORG}.accounts.turbomechanica.ai/oauth/token",
    json={
        "grant_type": "client_credentials",
        "client_id": CLIENT_ID,
        "client_secret": CLIENT_SECRET,
        "audience": "https://api.turbomechanica.ai",
    },
).json()["access_token"]

base = f"https://api.{ORG}.turbomechanica.ai/external"
headers = {"Authorization": f"Bearer {token}"}
params = {"start_time": "2025-06-01T00:00:00Z", "end_time": "2025-06-02T00:00:00Z"}

first = requests.get(f"{base}/v1/equipments/3/data", params=params, headers=headers).json()
pages = [first]
for page in range(2, first["total_pages"] + 1):
    pages.append(
        requests.get(
            f"{base}/v1/equipments/3/data",
            params={**params, "page": page, "snapshot_id": first["snapshot_id"]},
            headers=headers,
        ).json()
    )