Create run

POST/v2/runs

Authorization

api_key

AuthorizationBearer <token>

API key for authentication. Use format: Bearer YOUR_API_KEY

In: header

Overall test result. Use PASS when test succeeds, FAIL when test fails but script execution completed successfully, ERROR when script execution fails, TIMEOUT when test exceeds time limit, ABORTED for manual script interruption.

Value in"PASS" | "FAIL" | "ERROR" | "TIMEOUT" | "ABORTED"

procedure_id*string

Procedure ID. Create the procedure in the app first, then find the auto-generated ID on the procedure page.

Match

^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$

Formatuuid

deployment_id?|null

client_run_ref?string

Idempotency reference for this upload, minted and persisted by the caller BEFORE the request is sent. When a second request carries the same reference, it is recognised as a retry of the first and returns the run already created rather than creating another one. That is what makes an upload safe to retry after a lost or timed-out response. The reference must be unique per organization and must never be reused for different data: derive it from the credential id returned at login plus a counter persisted locally (the CLI sends <credential id>_<counter>), never from a timestamp alone, since a clock can go backwards. Omit the field and every request creates a new run, exactly as before.

Length1 <= length <= 200

execution_id?|null

slot_key?|null

slot_name?|null

procedure_version?|null

operated_by?string

Operator who executed the test run: an email address or a free-text name. Honored only for API-key callers (user keys and station keys); browser session callers are auto-stamped with the session user and this field is ignored. An email matching a member of the calling organization links the run to that user account; any other value (a name, or an unrecognized email) is recorded verbatim as a declared operator name. Declared names are informative only — they are not verified identities.

Length1 <= length <= 254

started_at*string

ISO 8601 timestamp when the test run began execution. This timestamp will be used to track when the test execution started and for historical analysis of test runs. A separate created_at timestamp is stored internally server side to track upload date.

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_at*string

ISO 8601 timestamp when the test run finished execution.

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

serial_number*string

Unique serial number of the unit under test. Matched case-insensitively. If no unit with this serial number exists, one will be created.

Match^[a-zA-Z0-9_.:+-]+$

Length1 <= length <= 60

part_number?string

Component part number for the unit. Matched case-insensitively. This field is required if the part number cannot be extracted from the serial number (as set in the settings). This field takes precedence over extraction from serial number. A component with the provided or extracted part number will be created if one does not exist.

Match^[a-zA-Z0-9_.:+-]+$

Length1 <= length <= 60

revision_number?string

Hardware revision identifier for the unit. Matched case-insensitively. If none exist, a revision with this number will be created. If no revision is specified, the unit will be linked to the default revision of the part number.

Match^[a-zA-Z0-9_.:+-]+$

Length1 <= length <= 60

batch_number?string

Production batch identifier for grouping units manufactured together. Matched case-insensitively. If none exist, a batch with this batch number will be created. If no batch number is specified, the unit will not be linked to any batch.

Match^[a-zA-Z0-9_.:+-]+$

Length1 <= length <= 60

sub_units?array<>

Array of sub-unit serial numbers that are part of this main unit. Matched case-insensitively. Each sub-unit must already exist and will be linked as a sub-component of the main unit under test. If no sub-units are specified, the unit will be created without sub-unit relationships.

docstring?string

Additional notes or documentation about this test run.

Lengthlength <= 50000

phases?array<>

Array of test phases with measurements and results. Each phase represents a distinct stage of the test execution with timing information, outcome status, and optional measurements. If no phases are specified, the run will be created without phase-level organization of test data.

logs?array<>

Array of log messages generated during the test execution. Each log entry captures events, errors, and diagnostic information with severity levels and source code references. If no logs are specified, the run will be created without log entries.

metadata?

Custom metadata to attach to the run (max 50 keys). Plain object of key/value pairs; values can be string, number, or boolean. Type is detected from the value.

unit_metadata?

Custom metadata to upsert on the unit under test (max 50 keys per unit). PATCH semantics: keys not present here are preserved on the unit.

Response Body

`application/json`

curl -X POST "https://example.com/v2/runs" \  -H "Content-Type: application/json" \  -d '{    "outcome": "PASS",    "procedure_id": "550e8400-e29b-41d4-a716-446655440000",    "started_at": "2024-01-15T10:30:00Z",    "ended_at": "2024-01-15T10:35:30Z",    "serial_number": "SN-001234"  }'

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "ids": [
    "6e0346a3-e54d-40e3-9779-4ba1e707e35b"
  ]
}

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

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

{
  "message": "Forbidden",
  "code": "FORBIDDEN",
  "issues": []
}

{
  "message": "Not found",
  "code": "NOT_FOUND",
  "issues": []
}

{
  "message": "Conflict",
  "code": "CONFLICT",
  "issues": []
}

{
  "message": "Unprocessable content",
  "code": "UNPROCESSABLE_CONTENT",
  "issues": []
}

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

Create run

Authorization

Request Body

Response Body

200application/json

400application/json

401application/json

403application/json

404application/json

409application/json

422application/json

500application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`