List and filter batches

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 list batches
Station	Full	Stations can list batches

Endpoint

GET/v2/batches

Authorization

AuthorizationBearer <token>

API key for authentication. Use format: Bearer YOUR_API_KEY

In: header

Query Parameters

ids?array<string>

Filter by specific batch IDs.

numbers?array<string>

Filter by batch numbers.

created_after?string

Filter for batches created at or after this time.

Formatdate-time

created_before?string

Filter for batches created at or before this time.

Formatdate-time

limit?integer

Maximum number of batches to return. Use cursor to fetch additional results.

Default50

Range1 <= value <= 100

cursor?integer

Cursor for pagination (offset-based). Use with limit to fetch results in batches.

Range0 <= value

search_query?string

Search query to filter batches by batch number or unit serial number.

Lengthlength <= 100

part_numbers?array<string>

Filter batches by part numbers of contained units.

revision_numbers?array<string>

Filter batches by revision numbers of contained units.

sort_by?string

Field to sort results by.

Default"created_at"

Value in"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.batches.list(
    limit=50,
    ids=["550e8400-e29b-41d4-a716-446655440000"],
    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"),
    cursor=0,
    search_query="BATCH-2024",
    part_numbers=["PCB-V1.2", "PCB-V1.3"],
    revision_numbers=["1.0", "1.1"],
    sort_by="created_at",
    sort_order="desc"
)

# Handle response
print(result)

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "number": "BATCH-2024-001",
      "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"
      },
      "units": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "serial_number": "SN-2024-001234",
          "part": {
            "id": "550e8400-e29b-41d4-a716-446655440007",
            "number": "PCB-MAIN-001",
            "name": "Main Control Board",
            "revision": {
              "id": "550e8400-e29b-41d4-a716-446655440006",
              "number": "REV-A",
              "image": "https://example.com/revision-image.jpg"
            }
          }
        }
      ]
    }
  ],
  "meta": {
    "has_more": true,
    "next_cursor": 50
  }
}

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

How is this guide?