---
title: "Start, poll or cancel an owner voice-latency collection run"
method: POST
path: "/v1/diagnostics/owner-collection"
tags: ["System"]
---

# Start, poll or cancel an owner voice-latency collection run

`POST /v1/diagnostics/owner-collection`

## Request

- Base URL: `http://localhost:9998`
- URL: `http://localhost:9998/v1/diagnostics/owner-collection`
- Auth: HTTP bearer

Drives an owner-run voice-latency collection. `action` is `start`,
`status` or `cancel`, and `runId` is a lowercase UUID.

`start` also carries `root` (the run's owned directory) and base64
registrations (`manifest`, `roster`, `ownerRegistration`,
`runtimeRegistration`, `buildDeclaration`, `hardwareRegistration`). It
requires the running app's active hotkey tap, verifies the sealed inputs
and the producing build, and answers 202 with the admitted job.
`status` and `cancel` carry only `action` and `runId`, and answer 200
with the job. The body is limited to 1 MiB. No raw content is persisted
(`rawContentPersisted` is always false).

## Request body

- object
  - `action` 'start' | 'status' | 'cancel', required
  - `runId` string, uuid, required: Lowercase UUID naming the run.
  - `root` string: `start` only: the run's owned root directory.
  - `manifest` string, byte: `start` only: the run manifest (at most 128 KiB decoded).
  - `roster` string, byte: `start` only: the task roster (at most 128 KiB decoded).
  - `ownerRegistration` string, byte: `start` only: the owner registration (at most 64 KiB decoded).
  - `runtimeRegistration` string, byte: `start` only: the runtime profile (at most 64 KiB decoded).
  - `buildDeclaration` string, byte: `start` only: the producing build's declaration (see `POST /v1/diagnostics/build-receipt`).
  - `hardwareRegistration` string, byte: `start` only: the hardware registration (at most 128 KiB decoded).

## Response `200`

Job state (`status` / `cancel`)

- OwnerCollectionJob: State of an owner collection job. `cohorts`, `reloadsPrevented`, `processStart` and `processFinish` appear only once the job has completed.
  - `version` 1, required
  - `runId` string, uuid, required
  - `manifestDigest` string, required
  - `state` string, required: `admitted`, `running`, `cancelling`, `completed`, `cancelled` or `failed`. Tolerate unknown values.
  - `ownerEnabled` boolean, required
  - `terminal` boolean, required: True once the job's task has finished.
  - `completedTrials` integer, required
  - `rawContentPersisted` false, required
  - `reloadsPrevented` boolean
  - `cohorts` object[]: Per-task aggregates for the registered cohort.
  - `processStart` object: Producer process receipts captured at the start boundary.
  - `processFinish` object: Producer process receipts captured at the finish boundary.
  - `failure` string: Failure code when the job failed or was cancelled.

## Other responses

- `202`: Collection admitted and started (`start`)
- `400`: Invalid request
- `404`: No collection job matches that `runId`
- `409`: Owner configuration, permissions, the hotkey tap or producer proof are unavailable (`owner_unavailable`)
- `500`: Job status could not be encoded (`collection_failed`)

---

[API](https://skmtc.dev/modelpiper/apis/toolpiper-api.md) · [All operations](https://skmtc.dev/modelpiper/apis/toolpiper-api/llms.txt) · [OpenAPI document](https://skmtc.dev/modelpiper/apis/toolpiper-api/revisions/6722bf56385c?raw)