Events

The events endpoint returns timeline-style events for one or more machines over a short time window. It is intended for building live timeline views — overlays of cycles, steps, part counts, shifts, downtime reasons, and work order operations on a per-machine timeline.

Permissions

Endpoint	Method	Read-only Access	Read-write Access	Description
/api/v1/events	GET	✅	✅	Retrieve timeline events for the given machines and time window

GET /api/v1/events

Required role: read-only or read-write

Query parameters:

• from (required): ISO8601 start timestamp.
• to (required): ISO8601 end timestamp. Must be strictly after from.
• machine_foreign_ids: comma-separated list of machine foreign IDs to filter by. If omitted, all unarchived machines in the organisation are included.
• types: one or more event types to include. Any unrecognised values are ignored. Supported values:
  • cycle
  • step
  • part_count
  • shift_period
  • activity_reason
  • work_order_operation

Time-window limits

The events endpoint is designed for short windows, not historical exports.

• The maximum allowed window is 1 day.
• If to - from > 1 day, the endpoint responds with 422 Unprocessable Entity.
• If to <= from or either timestamp is missing, the endpoint responds with 422 Unprocessable Entity.

Example request

curl -X GET "https://your-org.trackmymachines.app/api/v1/events?from=2025-05-27T08:00:00Z&to=2025-05-27T16:00:00Z&machine_foreign_ids[]=MACHINE_001&machine_foreign_ids[]=MACHINE_002&types=step&types=activity_reason" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example response

[
  {
    "id": "evt_8h3KdL2pQrxV",
    "type": "step",
    "machine_foreign_id": "MACHINE_001",
    "from": "2025-05-27T10:00:00Z",
    "to": "2025-05-27T11:30:00Z",
    "duration_seconds": 5400,
    "label": "PART123"
  },
  {
    "id": "evt_R7nT4mZ9wKbY",
    "type": "activity_reason",
    "machine_foreign_id": "MACHINE_001",
    "from": "2025-05-27T11:30:00Z",
    "to": null,
    "duration_seconds": null,
    "label": "Tool change"
  }
]

Response fields

• id: prefixed external event identifier (evt_…), stable across DB reseeds.
• type: event type, underscored (cycle, step, part_count, shift_period, activity_reason, work_order_operation).
• machine_foreign_id: machine foreign ID (or null if not set).
• from: event start timestamp (ISO8601).
• to: event end timestamp (ISO8601), or null for in-flight events.
• duration_seconds: event duration in seconds, or null for in-flight events.
• label: a human-readable label derived from the underlying record (e.g. the part identifier for a step, the shift pattern name for a shift period, the downtime reason for an activity reason).

Internal database IDs (machine_id, numeric event IDs) are intentionally never exposed — only foreign / external identifiers cross the API boundary.

Error responses

• 422 Unprocessable Entity — { "error": "from and to are required ISO8601 timestamps" }
• 422 Unprocessable Entity — { "error": "to must be after from" }