List and filter units

API v2 Preview

The TofuPilot API v2.0 is currently in public preview and is subject to change as we stabilize until release (planned for Aug 2025).

Access

API Key	Access Level	Description
User	Full	Users can retrieve units they have permission to access
Station	Full	Stations can list units

Endpoint

GET/v2/units

Authorization

AuthorizationBearer <token>

API key for authentication. Use format: Bearer YOUR_API_KEY

In: header

Query Parameters

search_query?string

Search query to filter units by serial number.

ids?array<string>

Filter by specific unit IDs.

serial_numbers?array<string>

Filter by unit serial numbers.

part_numbers?array<string>

Filter by component part numbers.

revision_numbers?array<string>

Filter by revision numbers.

batch_numbers?array<string>

Filter by batch numbers. Use empty string ("") to filter for units without a batch.

created_after?string

Filter for units created at or after this time.

Formatdate-time

created_before?string

Filter for units created at or before this time.

Formatdate-time

created_by_user_ids?array<string>

Filter by user IDs who created the units.

created_by_station_ids?array<string>

Filter by station IDs that created the units.

exclude_units_with_parent?boolean

Exclude units that have a parent unit (show only top-level units).

Defaultfalse

limit?integer

Maximum number of units to return.

Default50

Range1 <= value <= 100

cursor?integer

Cursor for pagination. Use next_cursor from previous response to fetch next page.

sort_by?string

Field to sort results by.

Default"created_at"

Value in"serial_number" | "created_at"

sort_order?string

Sort order direction.

Default"desc"

Value in"asc" | "desc"

Response Body

from tofupilot.v2 import TofuPilot
from datetime import datetime, timedelta, timezone

# Initialize the TofuPilot client
client = TofuPilot()

# Execute the operation
result = client.units.list(
    limit=50,
    search_query="SN-001234",
    ids=["550e8400-e29b-41d4-a716-446655440000"],
    serial_numbers=["SN-001234", "SN-005678"],
    part_numbers=["PCB-V1.2", "PCB-V1.3"],
    revision_numbers=["1.0", "1.1"],
    batch_numbers="BATCH-2024-01,BATCH-2024-02,",
    created_after=datetime.fromisoformat("2024-01-15T10:30:00Z"),
    created_before=datetime.fromisoformat("2024-01-15T11:30:00Z"),
    created_by_user_ids=["550e8400-e29b-41d4-a716-446655440000"],
    created_by_station_ids=["550e8400-e29b-41d4-a716-446655440000"],
    exclude_units_with_parent="true",
    cursor=50,
    sort_by="created_at",
    sort_order="desc"
)

# Handle response
print(result)

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "serial_number": "SN-2024-001234",
      "created_at": "2024-01-15T10:30:00Z",
      "created_by_user": {
        "id": "550e8400-e29b-41d4-a716-446655440001",
        "name": "John Doe",
        "image": "https://example.com/user-avatar.jpg"
      },
      "created_by_station": {
        "id": "550e8400-e29b-41d4-a716-446655440002",
        "name": "Assembly Station 01",
        "image": "https://example.com/station-01.jpg"
      },
      "batch": {
        "id": "550e8400-e29b-41d4-a716-446655440005",
        "number": "BATCH-2024-Q1-001"
      },
      "parent": {
        "id": "550e8400-e29b-41d4-a716-446655440004",
        "serial_number": "SN-2024-001233"
      },
      "children": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440006",
          "serial_number": "SN-2024-001235"
        }
      ],
      "part": {
        "id": "550e8400-e29b-41d4-a716-446655440008",
        "number": "PCB-MAIN-001",
        "name": "Main Control Board",
        "revision": {
          "id": "550e8400-e29b-41d4-a716-446655440007",
          "number": "REV-A",
          "image": "https://example.com/revision-image.jpg"
        }
      },
      "last_run": {
        "id": "550e8400-e29b-41d4-a716-446655440009",
        "outcome": "PASS",
        "started_at": "2024-01-15T10:25:00Z",
        "ended_at": "2024-01-15T10:30:00Z",
        "procedure": {
          "id": "550e8400-e29b-41d4-a716-446655440010",
          "name": "PCB Assembly Test"
        }
      }
    }
  ],
  "meta": {
    "has_more": true,
    "next_cursor": 100
  }
}

{
  "code": "INTERNAL_SERVER_ERROR",
  "message": "Internal server error",
  "issues": []
}

How is this guide?