> ## Documentation Index
> Fetch the complete documentation index at: https://docs.perceptron.inc/llms.txt
> Use this file to discover all available pages before exploring further.

# Retrieve an egocentric job

> Retrieve an egocentric job with the Egocentric API.

Poll this endpoint until `status` is `completed` or `failed`. Treat any future, unknown status as unfinished. A job can remain unfinished after execution ends while its result and billing are finalized.

For `failed` jobs, inspect `error.fault` and `error.retryable`; the retry flag does not start another execution. See [job failures and retry guidance](https://docs.perceptron.inc/services/egocentric-limits-and-errors.md#read-job-failures).

For authentication, limits, and HTTP errors, see the [workflow](https://docs.perceptron.inc/services/egocentric.md) and [error guide](https://docs.perceptron.inc/services/egocentric-limits-and-errors.md).


## OpenAPI

````yaml api-reference/openapi.json GET /v1/egocentric/jobs/{job_id}
openapi: 3.1.0
info:
  title: Perceptron API
  contact:
    name: Perceptron API Support
    email: support@perceptron.inc
  version: 1.0.0
servers:
  - url: https://api.perceptron.inc
security: []
tags:
  - name: Chat Completions
    description: Chat completions API (OpenAI-compatible)
  - name: Detection
    description: Native Perceptron image detection API
  - name: Models
    description: Model listing and metadata API
  - name: Files
    description: File upload, listing, retrieval, and deletion API
  - name: Egocentric
    description: Video annotation batches, jobs and results
paths:
  /v1/egocentric/jobs/{job_id}:
    get:
      tags:
        - Egocentric
      summary: Retrieve an egocentric job
      description: Retrieve a job's status, timing and error information.
      operationId: get_job
      parameters:
        - name: job_id
          in: path
          description: Job identifier.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Job
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EgocentricJob'
        '400':
          description: Invalid request or query parameter
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PerceptronErrorResponse'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PerceptronErrorResponse'
        '404':
          description: Job not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PerceptronErrorResponse'
        '429':
          description: Request or submission limit reached
          headers:
            Retry-After:
              schema:
                type: string
              description: >-
                Seconds to wait before retrying; omitted for insufficient
                credits.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PerceptronErrorResponse'
        '500':
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PerceptronErrorResponse'
        '503':
          description: Temporarily unavailable
          headers:
            Retry-After:
              schema:
                type: string
              description: >-
                Seconds to wait before retrying; omitted for insufficient
                credits.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PerceptronErrorResponse'
      security:
        - ApiKeyAuth: []
components:
  schemas:
    EgocentricJob:
      type: object
      description: State, input attributes, timing, and failure information for one video.
      required:
        - object
        - id
        - batch_id
        - status
        - input_metadata
        - error
        - created_at
        - started_at
        - execution_finished_at
        - finished_at
        - expires_at
      properties:
        batch_id:
          $ref: '#/components/schemas/BatchId'
          description: Identifier of the batch containing this job.
        created_at:
          type: string
          format: date-time
          description: UTC time the job's batch was accepted.
        error:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/JobError'
              description: Failure information when status is failed; null otherwise.
        execution_finished_at:
          type:
            - string
            - 'null'
          format: date-time
          description: >-
            Actual execution end; null if the job never ran or the time is
            unknown.
        expires_at:
          type:
            - string
            - 'null'
          format: date-time
          description: >-
            Result retention expiry, 30 days after finished_at; null until the
            job finishes.
        finished_at:
          type:
            - string
            - 'null'
          format: date-time
          description: >-
            Time result storage and usage settlement finished; null until the
            job is final.
        id:
          $ref: '#/components/schemas/JobId'
          description: Unique job identifier.
        input_metadata:
          $ref: '#/components/schemas/InputMetadata'
          description: Video attributes; each unknown attribute is null.
        object:
          type: string
          description: Object type, always egocentric.job.
          example: egocentric.job
        started_at:
          type:
            - string
            - 'null'
          format: date-time
          description: >-
            Actual execution start; null if the job never ran or the time is
            unknown.
        status:
          $ref: '#/components/schemas/JobStatus'
          description: Current public state; completed and failed are final.
    PerceptronErrorResponse:
      type: object
      description: Native Perceptron error response format.
      required:
        - error
      properties:
        error:
          $ref: '#/components/schemas/PerceptronErrorDetail'
    BatchId:
      type: string
    JobError:
      type: object
      description: The reason a job failed and whether a new submission could succeed.
      required:
        - code
        - message
        - fault
        - retryable
      properties:
        code:
          type: string
          description: Public failure code.
        fault:
          $ref: '#/components/schemas/JobFault'
          description: Whether the cause is an input/account problem or a service failure.
        message:
          type: string
          description: Explanation of the failure.
        retryable:
          type: boolean
          description: >-
            Whether resubmitting the same input could succeed after the cause is
            resolved; not an automatic retry request.
    JobId:
      type: string
    InputMetadata:
      type: object
      description: >-
        Descriptive video attributes retained after input cleanup; unknown
        values are null.
      required:
        - filename
        - file_extension
        - container
        - video_codec
      properties:
        container:
          type:
            - string
            - 'null'
          description: Container format of the validated video; null if unknown.
        file_extension:
          type:
            - string
            - 'null'
          description: >-
            Lowercase filename extension without its leading dot; null if
            unknown.
        filename:
          type:
            - string
            - 'null'
          description: >-
            Supplied filename or a name derived from the URL path; null if
            unavailable.
        video_codec:
          type:
            - string
            - 'null'
          description: Video codec of the validated video; null if unknown.
    JobStatus:
      type: string
      description: >-
        Public state: queued awaits preparation or capacity, submitted awaits
        execution,

        processing is running, completed succeeded, and failed finished without
        a result.

        A job retains its last public state until result storage and usage
        settlement finish.

        New states may be added; treat an unknown state as unfinished.
      enum:
        - queued
        - submitted
        - processing
        - completed
        - failed
    PerceptronErrorDetail:
      type: object
      description: Native Perceptron error detail.
      required:
        - message
      properties:
        code:
          type:
            - string
            - 'null'
        message:
          type: string
        param:
          type:
            - string
            - 'null'
        type:
          type:
            - string
            - 'null'
    JobFault:
      type: string
      description: >-
        Cause category: user_error is an input or account problem; system_error
        is a service failure.
      enum:
        - user_error
        - system_error
  securitySchemes:
    ApiKeyAuth:
      type: http
      scheme: bearer
      description: Bearer token authentication using your Perceptron API key

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.