> ## Documentation Index > Fetch the complete documentation index at: https://docs.clavata.ai/llms.txt > Use this file to discover all available pages before exploring further. # Get job label hits > 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`. ## OpenAPI ````yaml /openapi.json get /v1/jobs/{jobUuid}/labels openapi: 3.0.0 info: title: Clavata Public API v1 description: Endpoints for creating and managing jobs via the Clavata Public API. version: 1.0.0 contact: name: Clavata.ai url: https://clavata.ai email: support@clavata.ai servers: - url: https://gateway.app.clavata.ai:8443 security: - Bearer_Token: [] tags: - name: Public API description: Endpoints for creating and managing jobs via the Clavata Public API. paths: /v1/jobs/{jobUuid}/labels: get: tags: - Get Jobs summary: Get job label hits description: >- 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`. operationId: GatewayService_GetJobLabels parameters: - name: jobUuid description: job_uuid is the unique identifier of the job in: path required: true schema: type: string - name: jobResultId description: >- job_result_id scopes the response to a single result of the job (e.g. the ContentFeedEntry.job_result_id backing one content-feed row). When unset, labels from every result in the job are returned. in: query required: false schema: type: string - name: pageSize description: >- Pagination: maximum number of label hits to return. When unset or 0, defaults to 1000. Maximum 1000; larger values are treated as 1000. Negative values are rejected. in: query required: false schema: type: integer format: int32 - name: pageToken description: >- Pagination: the next_page_token from a previous response for the same job_uuid and job_result_id. Omit to fetch the first page. in: query required: false schema: type: string responses: '200': description: A successful response. content: application/json: schema: $ref: '#/components/schemas/v1GetJobLabelsResponse' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/rpcStatus' '429': description: Too Many Requests content: application/json: schema: $ref: '#/components/schemas/v1GRPCErrorResponse' '499': description: Precheck Failures (Canceled) content: application/json: schema: $ref: '#/components/schemas/v1PrecheckFailureResponse' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/rpcStatus' components: schemas: v1GetJobLabelsResponse: type: object properties: labels: type: array items: $ref: '#/components/schemas/GetJobLabelsResponseLabelHit' status: $ref: '#/components/schemas/v1JobStatus' error: $ref: '#/components/schemas/v1JobError' nextPageToken: type: string description: >- Set when more label hits remain after this page. Pass it as page_token to fetch the next page. rpcStatus: type: object properties: code: type: integer format: int32 message: type: string details: type: array items: $ref: '#/components/schemas/protobufAny' v1GRPCErrorResponse: type: object properties: code: type: integer format: int32 description: A [gRPC status code](https://grpc.io/docs/guides/status-codes/) title: gRPC Status Code readOnly: true message: type: string description: The human-readable error message title: Error Message readOnly: true title: A gRPC Status response v1PrecheckFailureResponse: type: object properties: code: type: integer format: int32 description: A [gRPC status code](https://grpc.io/docs/guides/status-codes/) title: gRPC Status Code readOnly: true message: type: string description: The human-readable error message title: Error Message readOnly: true details: type: array items: $ref: '#/components/schemas/v1PrecheckFailure' description: An array of objects detailing why the content failed the prechecks. GetJobLabelsResponseLabelHit: type: object properties: label: type: string startMs: type: string format: int64 description: |- 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: type: string description: |- Human-readable start time of the label occurrence as HH:MM:SS.mmm. Populated whenever start_ms is set. modality: $ref: '#/components/schemas/v1Modality' score: type: number format: double description: The score the label received during evaluation. endMs: type: string format: int64 description: >- 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: type: string description: |- Human-readable end time of the label occurrence as HH:MM:SS.mmm. Populated whenever end_ms is set. frameStartMs: type: string format: int64 description: >- 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: type: string format: int64 frameStartTimecode: type: string description: |- Human-readable frame segment bounds as HH:MM:SS.mmm. Populated whenever the corresponding frame bound is set. frameEndTimecode: type: string transcriptStartMs: type: string format: int64 description: >- 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: type: string format: int64 transcriptStartTimecode: type: string description: |- Human-readable transcript chunk bounds as HH:MM:SS.mmm. Populated whenever the corresponding transcript bound is set. transcriptEndTimecode: type: string v1JobStatus: type: string enum: - JOB_STATUS_UNSPECIFIED - JOB_STATUS_PENDING - JOB_STATUS_RUNNING - JOB_STATUS_COMPLETED - JOB_STATUS_FAILED - JOB_STATUS_CANCELED default: JOB_STATUS_UNSPECIFIED title: The status of a job at the time of the response v1JobError: type: object properties: reason: $ref: '#/components/schemas/v1JobErrorReason' message: type: string description: >- 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. protobufAny: type: object properties: '@type': type: string additionalProperties: {} v1PrecheckFailure: type: object properties: type: $ref: '#/components/schemas/v1PrecheckFailureType' message: type: string title: An error message associated with the failure details: description: >- Details provides Additional about the failure. The shape will be different for each failure type. matchConfidence: $ref: '#/components/schemas/v1PrecheckMatchConfidence' v1Modality: type: string enum: - MODALITY_UNSPECIFIED - MODALITY_VIDEO - MODALITY_AUDIO - MODALITY_IMAGE - MODALITY_TEXT default: MODALITY_UNSPECIFIED v1JobErrorReason: type: string enum: - 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 default: JOB_ERROR_REASON_UNSPECIFIED description: >- 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). v1PrecheckFailureType: type: string enum: - PRECHECK_FAILURE_TYPE_UNSPECIFIED - PRECHECK_FAILURE_TYPE_NCMEC - PRECHECK_FAILURE_TYPE_UNSUPPORTED_IMAGE_FORMAT - PRECHECK_FAILURE_TYPE_INVALID_IMAGE default: PRECHECK_FAILURE_TYPE_UNSPECIFIED description: |2- - PRECHECK_FAILURE_TYPE_UNSPECIFIED: The precheck failure type is not specified - PRECHECK_FAILURE_TYPE_NCMEC: The content has been identified as CSAM due to its hash matching an entry in the NCMEC database. - PRECHECK_FAILURE_TYPE_UNSUPPORTED_IMAGE_FORMAT: The image format is not supported. - PRECHECK_FAILURE_TYPE_INVALID_IMAGE: The provided image is invalid or corrupted. v1PrecheckMatchConfidence: type: string enum: - PRECHECK_MATCH_CONFIDENCE_UNSPECIFIED - PRECHECK_MATCH_CONFIDENCE_EXACT - PRECHECK_MATCH_CONFIDENCE_HIGH - PRECHECK_MATCH_CONFIDENCE_MEDIUM - PRECHECK_MATCH_CONFIDENCE_LOW default: PRECHECK_MATCH_CONFIDENCE_UNSPECIFIED description: |2- - PRECHECK_MATCH_CONFIDENCE_UNSPECIFIED: Default / legacy / non-CSAM. Not a customer-facing confidence tier. - PRECHECK_MATCH_CONFIDENCE_EXACT: Exact match (NCMEC direct md5/sha1 hash lookup). Highest confidence; customers may auto-enforce. - PRECHECK_MATCH_CONFIDENCE_HIGH: PhotoDNA perceptual match, closest distance band (near-duplicate). - PRECHECK_MATCH_CONFIDENCE_MEDIUM: PhotoDNA perceptual match, middle distance band (moderate similarity). - PRECHECK_MATCH_CONFIDENCE_LOW: PhotoDNA perceptual match, farthest distance band (loose similarity; review recommended). securitySchemes: Bearer_Token: type: http scheme: bearer bearerFormat: JWT ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.