List and filter batches

Retrieve batches with associated units, serial numbers, and part revisions using cursor-based pagination.

Access

API Key	Access Level	Description
User	Full	Users can read batchs
Station	Full	Stations can read batchs

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.

Match

^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$

Formatdate-time

created_before?string

Filter for batches created at or before this time.

Match

^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$

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 <= 9007199254740991

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 number of contained units.

revision_numbers?array<string>

Filter batches by revision number 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"
      },
      "created_by_station": {
        "id": "550e8400-e29b-41d4-a716-446655440002",
        "name": "Assembly Station 01"
      },
      "unit_count": 150
    }
  ],
  "meta": {
    "has_more": true,
    "next_cursor": 50
  }
}

{
  "message": "Bad request",
  "code": "BAD_REQUEST",
  "issues": []
}

{
  "message": "Unauthorized",
  "code": "UNAUTHORIZED",
  "issues": []
}

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

How is this guide?