Step Events
The step events endpoint allows you to retrieve, create, and finish jobs in your manufacturing process. TrackMyMachines uses this data to produce reports, calculate estimated finish times and alert you when your machines run jobs exceeding the quoted time from your ERP system.
Permissions
| Endpoint | Method | Read-only Access | Read-write Access | Description |
|---|---|---|---|---|
/api/v1/step_events |
GET | ✅ | ✅ | Retrieve step events |
/api/v1/step_events |
POST | ❌ | ✅ | Create a new step event, and finish it with an optional parameter |
Endpoints
GET /api/v1/step_events
Retrieves step events based on the provided filters.
Required Role: Read-only or Read-write
Query Parameters:
from: Start of the time range for filtering events (default: current week)to: End of the time range for filtering events (default: current week)machine_ids: Comma-separated list of machine IDs to filter events by
Example Request:
curl -X GET "https://your-org.trackmymachines.com/api/v1/step_events?from=2025-05-20&to=2025-05-27&machine_ids=1,2,3" \
-H "Authorization: Bearer YOUR_API_KEY"
Example Response:
[
{
"id": 15610,
"tzrange": "2025-06-18 09:00:00 UTC...Infinity",
"started_at": "2025-06-18T09:00:00.000Z",
"ended_at": null,
"eventable_type": "Step",
"eventable_id": 709,
"machine_id": 6,
"cycle_count": 273,
"minimum_cycle_time": 33,
"median_cycle_time": 46,
"maximum_cycle_time": 64,
"total_in_cycle_time": 12833,
"part_count": 243,
"time_to_first_part_count": 1637024,
"minimum_time_between_part_counts": 135,
"maximum_time_between_part_counts": 1127,
"median_time_between_part_counts": 145,
"load_time": 89,
"total_part_count_time": 37568,
"total_dead_time": 4763,
"metadata": {
"work_order_id": "",
"quantity_expected": "15"
},
"machine_name": "Machine 1",
"display_name": "1677723 Op10",
"range": "2025-06-18 09:00:00 UTC...Infinity"
},
{
"id": 18315,
"tzrange": "2025-06-27 16:23:00 UTC...Infinity",
"started_at": "2025-06-27T16:23:00.000Z",
"ended_at": null,
"eventable_type": "Step",
"eventable_id": 709,
"machine_id": 9,
"cycle_count": 273,
"minimum_cycle_time": 10,
"median_cycle_time": 46,
"maximum_cycle_time": 64,
"total_in_cycle_time": 12916,
"part_count": 242,
"time_to_first_part_count": 832793,
"minimum_time_between_part_counts": 135,
"maximum_time_between_part_counts": 1135,
"median_time_between_part_counts": 146,
"load_time": 89,
"total_part_count_time": 37543,
"total_dead_time": 4873,
"metadata": {
"work_order_id": "",
"quantity_expected": "25"
},
"machine_name": "Machine 4",
"display_name": "1677723 Op10",
"range": "2025-06-27 16:23:00 UTC...Infinity"
}
]
POST /api/v1/step_events
Clock on a job, creating a “Step Event in the timeline”.
Clocking on a job with parts, routes or steps that don’t exist will create them in TMM automatically.
This endpoint is idempotent across requests with the same body, meaning you can retry requests without fear of creating duplicate events.
It’s possible to start a job with this endpoint that hasn’t been finished yet. To finish a job that’s been started, send the same minimum required parameters along with the optional finish parameter.
Required Role: Read-write
Request Body:
{
"step_event": {
"machine_display_name": "Machine1",
"start": "2025-05-27T10:00:00Z",
"user_email": "user@example.com",
"part_unique_identifier": "PART123",
"part_issue": "A",
"recipe_version": "1",
"step_number": "10",
"step_expected_cycle_time": 120,
"step_expected_setup_time": 30,
"qty_expected": 5,
"wo_number": "WO-123"
}
}
Required Fields:
machine_display_name: Display name of the machinestart: Start timestamp (ISO8601)user_email: Email of the user associated with the eventpart_unique_identifier: Unique identifier for the partrecipe_version: Version of the recipestep_number: Step number in the recipe
Optional Fields:
part_issue: Part issue numberfinish: Finish timestamp (ISO8610)step_expected_cycle_time: Expected cycle time (seconds)step_expected_setup_time: Expected setup time (seconds)qty_expected: Expected quantityqty_made: Quantity madeqty_scrapped: Quantity scrappedwo_number: Work order number
Example Response:
{
"event": {
"machine_id": 6,
"range": "2025-05-27 10:00:00 UTC...",
"eventable_type": "Step",
"eventable_id": 3092,
"ending_type": "manual",
"id": 7785,
"deleted_at": null,
"metadata": {
"qty_expected": 5,
"wo_number": "WO-123"
},
"created_at": "2025-05-27T10:01:45.397Z",
"updated_at": "2025-05-27T10:01:45.397Z",
"user_id": 3,
"tzrange": "2025-05-27 10:00:00 UTC...",
"machine_name": "Machine 1",
"display_name": "PART123 Op10"
},
"step": {
"id": 3092,
"machine_id": null,
"recipe_id": 2443,
"number": "10",
"description": null,
"created_at": "2025-05-27T10:01:45.369Z",
"updated_at": "2025-05-27T10:01:45.369Z",
"expected_cycle_time": 120,
"expected_setup_time": 30
},
"recipe": {
"id": 2443,
"organisation_id": null,
"part_id": 2348,
"description": null,
"created_at": "2025-05-27T10:01:45.363Z",
"updated_at": "2025-05-27T10:01:45.363Z",
"version": 1
},
"part": {
"id": 2348,
"unique_identifier": "PART123",
"organisation_id": 3,
"description": null,
"created_at": "2025-05-27T10:01:45.358Z",
"updated_at": "2025-05-27T10:01:45.358Z"
}
}
Error Handling
Machine Not Found
{
"error": "Machine not found"
}
User Not Found
{
"error": "User not found"
}
No Active Step Event
{
"error": "No active step event found for this machine"
}
Invalid End Timestamp
{
"error": "Invalid end timestamp"
}
Read-only API Key Attempting Write Operation
{
"error": "This API key does not have write permissions"
}
Record Invalid
Record invalid means that validations for the record have not passed, the error message will detail the reason for vaildation failure
{
"error": "Validation Failed: Error message"
}