TofuPilotTofuPilot
API & SDKsREST APIRuns

List and filter runs

GET/v2/runs

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 runs by run ID (partial match) or unit serial number.

ids?array<>

Filter by specific run IDs.

outcomes?array<>

Filter by run outcomes.

procedure_ids?array<>

Filter by procedure IDs.

procedure_versions?array<string>

Filter by procedure versions.

deployment_ids?array<>

Filter by deployment IDs the run executed from.

execution_ids?array<>

Filter by execution IDs: every slot run of the given multi-slot executions.

slot_keys?array<>

Filter by fixture slot keys, e.g. every run produced by slot s03.

slot_names?array<>

Filter by fixture slot names, the human label a station gives a slot.

environments?array<>

Filter by deployment environment (production, preview, development).

serial_numbers?array<string>

Filter by unit serial numbers.

samples?array<>

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

part_numbers?array<string>

Filter by component part numbers.

revision_numbers?array<string>

Filter by revision identifiers.

batch_numbers?array<string>

Filter by batch numbers.

duration_min?string

Filter for runs with duration greater than or equal to this value (ISO 8601 duration).

Match^P(?:(\d+W)|(?!.*W)(?=\d|T\d)(\d+Y)?(\d+M)?(\d+D)?(T(?=\d)(\d+H)?(\d+M)?(\d+([.,]\d+)?S)?)?)$
Formatduration
duration_max?string

Filter for runs with duration less than or equal to this value (ISO 8601 duration).

Match^P(?:(\d+W)|(?!.*W)(?=\d|T\d)(\d+Y)?(\d+M)?(\d+D)?(T(?=\d)(\d+H)?(\d+M)?(\d+([.,]\d+)?S)?)?)$
Formatduration
started_after?string

Filter for runs started at or after this timestamp.

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 runs started at or before this timestamp.

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
ended_after?string

Filter for runs ended at or after this timestamp.

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
ended_before?string

Filter for runs ended at or before this timestamp.

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_after?string

Filter for runs created at or after this timestamp.

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 runs created at or before this timestamp.

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

created_by_station_ids?array<>

Filter by station IDs that created the runs.

operated_by_ids?array<>

Filter by user IDs who operated the runs. Combined with operated_by_names as OR.

operated_by_names?array<>

Filter by declared operator names (operators without a TofuPilot account). Exact match; combined with operated_by_ids as OR.

limit?integer

Maximum number of runs to return per page.

Default50
Range1 <= value <= 100
cursor?integer

Offset position for pagination. Use the next_cursor from the previous response to get the next page.

Range-9007199254740991 <= value <= 9007199254740991
sort_by?string

Field to sort results by.

Default"started_at"
Value in"started_at" | "created_at" | "duration" | "outcome" | "serial_number" | "part_number" | "revision_number"
sort_order?string

Sort order direction.

Default"desc"
Value in"asc" | "desc"
include_metadata?boolean

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

Defaultfalse

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v2/runs"
{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "created_at": "2024-01-15T10:30:00Z",
      "started_at": "2024-01-15T10:35:00Z",
      "ended_at": "2024-01-15T10:37:30Z",
      "duration": "PT2M30S",
      "outcome": "PASS",
      "docstring": "Test run for production validation",
      "execution_id": "550e8400-e29b-41d4-a716-446655440000",
      "slot_key": "s03",
      "slot_name": "Slot 3",
      "created_by_user": {
        "id": "550e8400-e29b-41d4-a716-446655440001",
        "name": "John Doe",
        "email": "john.doe@example.com"
      },
      "created_by_station": {
        "id": "550e8400-e29b-41d4-a716-446655440002",
        "name": "Test Station 01"
      },
      "operated_by": {
        "id": "550e8400-e29b-41d4-a716-446655440001",
        "name": "John Doe",
        "email": "john.doe@example.com"
      },
      "procedure": {
        "id": "550e8400-e29b-41d4-a716-446655440003",
        "name": "PCB Functional Test",
        "version": {
          "id": "550e8400-e29b-41d4-a716-446655440010",
          "tag": "v2.1.0"
        }
      },
      "unit": {
        "id": "550e8400-e29b-41d4-a716-446655440004",
        "serial_number": "SN-2024-001234",
        "sample": null,
        "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"
          }
        },
        "batch": {
          "id": "550e8400-e29b-41d4-a716-446655440005",
          "number": "BATCH-2024-Q1-001"
        }
      },
      "metadata": {
        "vendor": "Acme",
        "lot_size": 500,
        "qualified": true
      }
    }
  ],
  "meta": {
    "has_more": true,
    "next_cursor": 100
  }
}
{
  "message": "Bad request",
  "code": "BAD_REQUEST",
  "issues": []
}
{
  "message": "Unauthorized",
  "code": "UNAUTHORIZED",
  "issues": []
}
{
  "message": "Request timeout",
  "code": "TIMEOUT",
  "issues": []
}
{
  "message": "Internal server error",
  "code": "INTERNAL_SERVER_ERROR",
  "issues": []
}

How is this guide?

Get run GET

Get a run by ID, with its metadata, phases, measurements, and logs.

Update run PATCH

Link uploaded files to a run. Upload files via Initialize and Finalize first, then call this to attach them.