--- title: "Get job label hits" method: GET path: "/v1/jobs/{jobUuid}/labels" tags: ["Get Jobs"] --- # Get job label hits `GET /v1/jobs/{jobUuid}/labels` ## Request - Base URL: `https://gateway.app.clavata.ai:8443` - URL: `https://gateway.app.clavata.ai:8443/v1/jobs/{jobUuid}/labels` - Auth: HTTP bearer - TypeScript: (a function with typed inputs; its response is checked against the schema) Retrieves label occurrences for a job, projected to label, modality, score, and timed fields (start_ms/end_ms and their timecodes). Video frame hits are point-in-time (start only); audio chunk hits are ranged when end_ms is set. Set the optional job_result_id to scope the response to a single result of the job. Hits are paged in a stable order: results in the order they were recorded, and each result's hits in the order the evaluation recorded them (start time ascending for video). Omitting `page_size` uses the default of 1000. The maximum `page_size` is 1000. Negative `page_size` is rejected. When more hits remain, `next_page_token` is set; pass it as `page_token` with the same job_uuid and job_result_id to fetch the next page. An incomplete job returns its status with no labels and no `next_page_token`. Available to policy-first and label-first accounts; works on any job in the account, including jobs from `POST /v1/labels/evaluate`. ## Path parameters - `jobUuid` string, required ## Query parameters - `jobResultId` string - `pageSize` integer - `pageToken` string ## Response `200` A successful response. - V1GetJobLabelsResponse - `labels` GetJobLabelsResponseLabelHit[] - `label` string - `startMs` string, int64: Milliseconds from the start of the media where the label occurred. Populated for every modality. Video frame hits are point-in-time; audio chunk hits use the chunk's start bound. - `startTimecode` string: Human-readable start time of the label occurrence as HH:MM:SS.mmm. Populated whenever start_ms is set. - `modality` 'MODALITY_UNSPECIFIED' | 'MODALITY_VIDEO' | 'MODALITY_AUDIO' | 'MODALITY_IMAGE' | 'MODALITY_TEXT' - `score` number, double: The score the label received during evaluation. - `endMs` string, int64: Milliseconds from the start of the media where the label occurrence ends. Populated for ranged hits (audio chunks, ranged video) when an end bound is present; omitted for point-in-time video frames. - `endTimecode` string: Human-readable end time of the label occurrence as HH:MM:SS.mmm. Populated whenever end_ms is set. - `frameStartMs` string, int64: For video hits, the frame segment that produced this occurrence, in milliseconds on the video timeline. start_ms/end_ms carry the occurrence's own contiguous range (the overlap of the frame segment and transcript chunk); these fields carry the frame segment's full bounds. Absent for non-video hits. - `frameEndMs` string, int64 - `frameStartTimecode` string: Human-readable frame segment bounds as HH:MM:SS.mmm. Populated whenever the corresponding frame bound is set. - `frameEndTimecode` string - `transcriptStartMs` string, int64: For video hits, the transcript chunk that produced this occurrence, in milliseconds on the video timeline. Absent when the occurrence has no transcript (image-only video segments) and for non-video hits. - `transcriptEndMs` string, int64 - `transcriptStartTimecode` string: Human-readable transcript chunk bounds as HH:MM:SS.mmm. Populated whenever the corresponding transcript bound is set. - `transcriptEndTimecode` string - `status` 'JOB_STATUS_UNSPECIFIED' | 'JOB_STATUS_PENDING' | 'JOB_STATUS_RUNNING' | 'JOB_STATUS_COMPLETED' | 'JOB_STATUS_FAILED' | 'JOB_STATUS_CANCELED' - `error` V1JobError: Details about a terminal job failure. Job status remains the authoritative success/failure signal; this message provides a stable machine-readable reason and a human-readable explanation when status is JOB_STATUS_FAILED. message is the fixed explanation for the reason, not worker error text, so it is safe to display but not useful to parse — branch on reason instead. - `reason` 'JOB_ERROR_REASON_UNSPECIFIED' | 'JOB_ERROR_REASON_JOB_FAILED' | 'JOB_ERROR_REASON_VIDEO_VALIDATION_FAILURE' | 'JOB_ERROR_REASON_VIDEO_SCENE_CEILING_EXCEEDED' | 'JOB_ERROR_REASON_HLS_REMUX_TIMEOUT_EXHAUSTED' | 'JOB_ERROR_REASON_EXECUTION_DEADLINE_EXCEEDED' | 'JOB_ERROR_REASON_ADMISSION_QUEUE_TIMEOUT' | 'JOB_ERROR_REASON_ADMISSION_FAILED' | 'JOB_ERROR_REASON_TRANSCRIPT_CHUNK_ARTIFACT_INVALID' | 'JOB_ERROR_REASON_QUOTA_EXCEEDED' | 'JOB_ERROR_REASON_CONTENT_BLOCKED' | 'JOB_ERROR_REASON_CONTENT_PRECHECK_FAILED' | 'JOB_ERROR_REASON_VIDEO_SOURCE_UNREACHABLE' | 'JOB_ERROR_REASON_CONTENT_TOO_LARGE': Why a job failed. Values are public API: existing ones are never renumbered or repurposed, but new ones are added as new failure modes appear, so clients must handle unrecognized values rather than assuming this list is complete. - JOB_ERROR_REASON_UNSPECIFIED: The reason was not recorded. Jobs that failed before this field existed report no error at all rather than this value. - JOB_ERROR_REASON_JOB_FAILED: The job failed for a reason with no more specific classification. - JOB_ERROR_REASON_VIDEO_VALIDATION_FAILURE: The submitted video could not be validated or decoded. - JOB_ERROR_REASON_VIDEO_SCENE_CEILING_EXCEEDED: The submitted video exceeds the maximum number of analyzable scenes. - JOB_ERROR_REASON_HLS_REMUX_TIMEOUT_EXHAUSTED: The submitted video stream could not be retrieved before the remux timeout. - JOB_ERROR_REASON_EXECUTION_DEADLINE_EXCEEDED: The job exceeded its execution deadline. - JOB_ERROR_REASON_ADMISSION_QUEUE_TIMEOUT: The job timed out waiting to be admitted for processing. - JOB_ERROR_REASON_ADMISSION_FAILED: The job could not be admitted for processing. - JOB_ERROR_REASON_TRANSCRIPT_CHUNK_ARTIFACT_INVALID: The audio transcript could not be processed. - JOB_ERROR_REASON_QUOTA_EXCEEDED: The customer's evaluation quota was exhausted before the job could start. - JOB_ERROR_REASON_CONTENT_BLOCKED: The submitted content was rejected by a pre-evaluation content check. - JOB_ERROR_REASON_CONTENT_PRECHECK_FAILED: The pre-evaluation content check could not be completed. - JOB_ERROR_REASON_VIDEO_SOURCE_UNREACHABLE: The submitted video URL could not be accessed (for example HTTP 403/404). - JOB_ERROR_REASON_CONTENT_TOO_LARGE: The evaluation prompt exceeds every attempted model's context window. - `message` string - `nextPageToken` string: Set when more label hits remain after this page. Pass it as page_token to fetch the next page. ## Other responses - `400`: Bad Request - `429`: Too Many Requests - `499`: Precheck Failures (Canceled) - `default`: An unexpected error response. ## Changes - **2026-10-16** `d7a854b0070f`: 1 info - endpoint added [Operation history](https://skmtc.dev/clavata/apis/clavata-public-api-v1/changes/v1/jobs/:jobUuid/labels/get.md) --- [API](https://skmtc.dev/clavata/apis/clavata-public-api-v1.md) - [All operations](https://skmtc.dev/clavata/apis/clavata-public-api-v1/llms.txt) - [OpenAPI document](https://skmtc.dev/clavata/apis/clavata-public-api-v1/revisions/d7a854b0070f?raw)