List and filter units

GET/v2/units

Authorization

api_key

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

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 ("") alone to filter for units without a batch.

procedure_ids?array<>

Filter by procedure IDs of runs on the unit.

outcomes?array<>

Filter by outcomes of runs on the unit.

started_after?string

Filter for units with runs started 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

started_before?string

Filter for units with runs started 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

latest_only?boolean

When true, procedure/outcome/started filters apply only to the latest run per unit.

Defaultfalse

run_count_min?integer

Filter for units with at least this many test runs.

Range0 <= value <= 9007199254740991

run_count_max?integer

Filter for units with at most this many test runs.

Range0 <= value <= 9007199254740991

created_after?string

Filter for units 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 units 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

created_by_user_ids?array<>

Filter by user IDs who created the units.

created_by_station_ids?array<>

Filter by station IDs that created the units.

exclude_units_with_parent?boolean

Exclude sub-units (units that have a parent). Shows only top-level units.

Defaultfalse

samples?array<>

Filter by reference-sample classification. Omit to include all units (production + references). Pass ['golden'] for known-good references only, ['failing'] for known-faulty references only, or any combination.

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.

Range-9007199254740991 <= value <= 9007199254740991

sort_by?string

Field to sort results by. last_run_at sorts by most recent test run date. last_run_procedure sorts by procedure name of the last run.

Default"created_at"

Value in"serial_number" | "created_at" | "last_run_at" | "part_number" | "last_run_procedure"

sort_order?string

Sort order direction.

Default"desc"

Value in"asc" | "desc"

metadata?

Filter units by custom metadata. Supports up to 5 keys per request. Per-key operators: string {in: [...]}/{contains: "..."}, number {gte, lte, gt, lt, eq}, bool {eq: true|false}.

include_metadata?boolean

When true, includes the unit metadata array in the response. Defaults to false to keep payloads small.

Defaultfalse

Response Body

`application/json`

curl -X GET "https://example.com/v2/units"

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "serial_number": "SN-2024-001234",
      "created_at": "2024-01-15T10:30:00Z",
      "sample": null,
      "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"
      },
      "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"
        }
      },
      "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"
        }
      },
      "metadata": {
        "vendor": "Acme",
        "lot_size": 500,
        "qualified": true
      }
    }
  ],
  "meta": {
    "has_more": true,
    "next_cursor": 100
  }
}

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

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

List and filter units

Authorization

Query Parameters

Response Body

200application/json

401application/json

500application/json

`application/json`

`application/json`

`application/json`