API referenceEquipment
List equipment events
A piece of equipment's history, newest first: what it was used on, and its calibration and preventive maintenance records. Each event has the fields of its kind; the others are null.
GET
https://app.xplantpro.com/Scope
read:equipmentWithout kind you get every kind in one list, which pages by cursor only. Send kind to read one kind, which pages by cursor or offset.
This history is part of equipment calibration, which not every plan includes.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string (uuid) | Yes | The record's id. |
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
kind | "used" | "calibration" | "preventive_maintenance" | No | Only this kind of event: used, calibration or preventive_maintenance. Without it you get every kind, newest first. |
from | string (date-time) | No | Only events at or after this time, as an ISO 8601 timestamp. |
to | string (date-time) | No | Only events at or before this time, as an ISO 8601 timestamp. |
limit | integer | No | Page size. Values above 200 are capped at 200. Default 50. From 1 to 200. |
offset | integer | No | Number of records to skip. Prefer cursor where a list offers it: an offset shifts when records are added ahead of it. Default 0. At least 0. |
cursor | string | No | Continue from the previous page: pass its meta.next_cursor unchanged, with the same filters. Treat it as opaque. Not combinable with offset. Up to 2048 characters. |
Example
curl "https://app.xplantpro.com/api/v1/equipment/8b0d2f4a-6c8e-4a0b-8d2f-4a6c8e0b2d4f/events?kind=calibration" \
-H "Authorization: Bearer $XPLANT_API_KEY"Response
200 with { "ok": true, "data": … }. data is an array. To get the next page, pass meta.next_cursor back as cursor; it is null on the last page. See Pagination.
| Field | Type | Required | Description |
|---|---|---|---|
id | string (uuid) | Yes | — |
equipment_id | string (uuid) | Yes | — |
kind | string | Yes | used for a use; calibration, preventive_maintenance for a maintenance record. |
occurred_at | string | null | Yes | When it happened — the use, or the work — as an ISO 8601 timestamp in UTC. |
outcome | string | null | Yes | Maintenance only: pass, pass_after_adjustment, out_of_tolerance, fail, not_performed. |
subject_type | string | null | Yes | Uses only — what it was used on: sop_log, media_batch, plant_transfer, explant_transfer, contamination_log. |
subject_id | string | null (uuid) | Yes | Uses only: the id of that record. |
subject_label | string | null | Yes | Uses only: a readable name for that record. |
performed_by_name | string | null | Yes | Maintenance only: who did the work, a person or a service company. |
provider | string | null | Yes | Maintenance only: the service provider, if any. |
as_found_condition | string | null | Yes | Maintenance only: the state the instrument was found in, before any adjustment. |
as_left_condition | string | null | Yes | Maintenance only: the state it was left in. |
result_summary | string | null | Yes | — |
certificate_number | string | null | Yes | — |
certificate_url | string | null | Yes | — |
next_due_at | string | null | Yes | Maintenance only: the next due date the work set, as an ISO 8601 date. |
notes | string | null | Yes | — |
{
"ok": true,
"data": [
{
"id": "3f7a9c20-8e41-4b5d-a6c2-1d9e0b7f5a34",
"equipment_id": "8c2f4e61-5a3b-4d7e-9b10-3e6a2c9d4f18",
"kind": "used",
"occurred_at": "2026-09-24T07:15:00.000Z",
"outcome": null,
"subject_type": "media_batch",
"subject_id": "b1e6d8a4-2c7f-4e93-8a05-6f4c3d2b1a90",
"subject_label": "MS half strength, batch 14",
"performed_by_name": null,
"provider": null,
"as_found_condition": null,
"as_left_condition": null,
"result_summary": null,
"certificate_number": null,
"certificate_url": null,
"next_due_at": null,
"notes": "121 °C for 20 minutes"
},
{
"id": "c5d2e8f1-7a3b-4c69-9e14-0b8a6d4f2e57",
"equipment_id": "8c2f4e61-5a3b-4d7e-9b10-3e6a2c9d4f18",
"kind": "calibration",
"occurred_at": "2026-06-02T08:30:00.000Z",
"outcome": "pass",
"subject_type": null,
"subject_id": null,
"subject_label": null,
"performed_by_name": "Example Calibration Services",
"provider": "Example Calibration Services",
"as_found_condition": "Within tolerance",
"as_left_condition": "Within tolerance",
"result_summary": "Temperature and pressure checked at three points.",
"certificate_number": "ECS-2026-0412",
"certificate_url": null,
"next_due_at": "2026-12-02",
"notes": null
}
]
}The envelope can also carry meta:
| Field | Type | Required | Description |
|---|---|---|---|
next_cursor | string | null | Yes | Pass as cursor to fetch the next page. null means this is the last page. |
| Response header | Meaning |
|---|---|
X-Request-Id | Identifies this request. Include it when you contact support. |
Errors
| Status | Code | When |
|---|---|---|
401 | UNAUTHORIZED | The key is missing, malformed or revoked, or its owner is no longer a member of the workspace. |
402 | PAID_PLAN_REQUIRED | The workspace's plan does not include the API. The full API is included with xPlant+ Teams and Enterprise; on Hobby and Pro Lab, keys can connect devices only. |
402 | FEATURE_NOT_INCLUDED | Equipment calibration and maintenance records are not included in your plan. |
403 | FORBIDDEN | The key lacks a scope this operation requires, or its owner's current role in the workspace cannot use it — a key never does more than its owner can in xPlant. error names the scope, and for a role, the role it needs. |
403 | DEVICE_TOKEN_NOT_ACCEPTED | A device token was sent; this operation needs a workspace API key. |
404 | NOT_FOUND | No record with this id exists in the key's workspace. |
422 | VALIDATION_ERROR | Both cursor and offset were sent; use one. |
422 | INVALID_CURSOR | The cursor is malformed, or came from a different list or different filters. Start again without it. |
422 | VALIDATION_ERROR | A query parameter is malformed, from is later than to, or offset was sent without kind. error names the parameter. |
429 | RATE_LIMIT_EXCEEDED | Too many requests for this key, device token or workspace. Wait Retry-After seconds. |
500 | LAB_EQUIPMENT_QUERY_FAILED | The equipment could not be read. Retry later. |
500 | FEATURE_CHECK_FAILED | Your plan could not be checked. Retry later. |
500 | EQUIPMENT_EVENT_QUERY_FAILED | The history could not be read. Retry later. |
Branch on code, never on the error text. See Errors.
Get a piece of equipment
One piece of equipment, with its calibration and maintenance due dates.
Record an equipment event
Records that a piece of equipment was used, calibrated or serviced — from the instrument itself, or from any system that knows. Events are history: there is no update or delete, and a correction is another event.