Book a demo

Clocking on and Clocking off jobs

Wednesday May 28, 2025

Rowan Easter-Robinson

Step Events

The step events endpoint allows you to retrieve, create, and finish step events in your manufacturing process. These are called step events, because a step is a part of a recipe, and a recipe is a set of steps to make a part. Every time something happens on a machine in time, it’s an event of a certain type. Starting a job on a machine really means starting an operation (or step). Since this is an event of a certain type, it’s a step event.

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
/api/v1/step_events/finish PATCH ❌ ✅ Finish an existing step event

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:

{
  "data": [
    {
      "date": "2025-05-20",
      "machine": "Machine1",
      "events_count": 5,
      "total_cycle_time": 3600
    },
    {
      "date": "2025-05-21",
      "machine": "Machine1",
      "events_count": 7,
      "total_cycle_time": 4200
    }
  ]
}

POST /api/v1/step_events

Creates a new step event.

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",
    "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 machine
  • start: Start timestamp
  • user_email: Email of the user associated with the event
  • part_unique_identifier: Unique identifier for the part
  • recipe_version: Version of the recipe
  • step_number: Step number in the recipe

Optional Fields:

  • step_expected_cycle_time: Expected cycle time in seconds
  • step_expected_setup_time: Expected setup time in seconds
  • qty_expected: Expected quantity
  • wo_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"
    }
}

PATCH /api/v1/step_events/finish

Finishes an existing step event.

Required Role: Read-write

Request Body:

{
  "step_event": {
    "machine_display_name": "Machine1",
    "end": "2025-05-27T11:00:00Z",
    "qty_made": 42,
    "qty_scrapped": 3
  }
}

Required Fields:

  • machine_display_name: Display name of the machine

Optional Fields:

  • end: End timestamp
  • qty_made: Quantity made
  • qty_scrapped: Quantity scrapped

Example Response:

{
  "event": {
    "id": 123,
    "machine_id": 45,
    "user_id": 67,
    "tzrange": "2025-05-27T10:00:00Z..2025-05-27T11:00:00Z",
    "metadata": {
      "qty_expected": 5,
      "wo_number": "WO-123",
      "quantity_made": 42,
      "quantity_scrapped": 3
    }
  }
}

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"
}