> ## Documentation Index > Fetch the complete documentation index at: https://docs.spatius.ai/llms.txt > Use this file to discover all available pages before exploring further. # Get an Avatar job > Returns a single Avatar creation job. Poll this endpoint after `POST /avatars` until `status` is `succeeded` (use `avatarId`) or `failed` (inspect `error`). A polling interval of 5-10 seconds is recommended. ## OpenAPI ````yaml /openapi/avatar-open-api.json get /avatar-jobs/{jobId} openapi: 3.0.3 info: title: Spatius API version: 1.0.0 description: >- The Spatius API lets you create and manage avatars programmatically. Submit a source image, poll the asynchronous creation job, and use the resulting avatar ID anywhere an avatar ID is accepted in your SDK integration. All endpoints require the `X-App-ID` and `X-API-Key` headers. See [Authentication](/api-reference/authentication) and [Errors and Limits](/api-reference/errors). servers: - url: https://console.spatius.ai/v1/open description: Spatius Console API (global) security: - AppId: [] ApiKey: [] tags: - name: Avatars description: >- Create Avatars and read the canonical Studio Avatar resources owned by your account. - name: Avatar Jobs description: Track asynchronous Avatar creation jobs. paths: /avatar-jobs/{jobId}: get: tags: - Avatar Jobs summary: Get an Avatar job description: >- Returns a single Avatar creation job. Poll this endpoint after `POST /avatars` until `status` is `succeeded` (use `avatarId`) or `failed` (inspect `error`). A polling interval of 5-10 seconds is recommended. operationId: getAvatarJob parameters: - name: jobId in: path required: true description: Job ID (UUID) returned by `POST /avatars`. schema: type: string format: uuid responses: '200': description: The requested job. content: application/json: schema: $ref: '#/components/schemas/GetAvatarJobResponse' examples: succeeded: summary: Succeeded job value: job: id: 6f1e2b3c-9a1d-4e5f-8b0a-2c4d6e8f0a1b status: succeeded name: Support Agent avatarId: a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d createdAt: '2026-07-25T09:30:00Z' updatedAt: '2026-07-25T09:47:12Z' completedAt: '2026-07-25T09:47:12Z' failed: summary: Failed job value: job: id: 7a8b9c0d-1e2f-4a5b-9c0d-3e4f5a6b7c8d status: failed name: Avatar-7a8b9c0d error: code: image_quality_rejected message: >- The source image did not pass Avatar image requirements. retryable: false createdAt: '2026-07-25T10:05:00Z' updatedAt: '2026-07-25T10:05:41Z' completedAt: '2026-07-25T10:05:41Z' '400': $ref: '#/components/responses/InvalidRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' components: schemas: GetAvatarJobResponse: type: object properties: job: $ref: '#/components/schemas/AvatarJob' AvatarJob: type: object description: An asynchronous Avatar creation job. properties: id: type: string format: uuid status: $ref: '#/components/schemas/JobStatus' name: type: string description: Display name the Avatar will receive. avatarId: type: string format: uuid description: ID of the created Avatar. Present only when `status` is `succeeded`. error: $ref: '#/components/schemas/AvatarJobError' createdAt: type: string format: date-time updatedAt: type: string format: date-time completedAt: type: string format: date-time description: Set when the job reaches `succeeded` or `failed`. Error: type: object description: The single public error envelope returned by every Spatius API endpoint. properties: error: type: object properties: code: type: string description: Stable machine-readable error code. enum: - unauthorized - forbidden - invalid_request - not_found - insufficient_avatar_units - rate_limit_exceeded - concurrency_limit_exceeded - service_unavailable - unsupported_input - internal_error message: type: string description: Human-readable explanation specific to this occurrence. requestId: type: string description: >- Unique identifier for this request. Quote it when contacting support. JobStatus: type: string description: Lifecycle status of an Avatar creation job. enum: - queued - processing - succeeded - failed AvatarJobError: type: object description: Stable public error returned when an Avatar creation job fails. properties: code: type: string description: Machine-readable failure code. enum: - source_download_failed - invalid_image - image_quality_rejected - preprocess_failed - avatar_generation_failed - internal_error message: type: string description: Human-readable explanation of the failure. retryable: type: boolean description: Whether resubmitting the same request may succeed. responses: InvalidRequest: description: >- The request is malformed or violates a precondition, such as a missing `imageUrl` or an invalid ID in the path. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: invalid_request message: imageUrl is required requestId: b3f0c2d1-4a5b-4c6d-8e9f-0a1b2c3d4e5f Unauthorized: description: >- The `X-App-ID` / `X-API-Key` pair is missing, does not match, or belongs to an inactive account. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: unauthorized message: Unauthorized. requestId: b3f0c2d1-4a5b-4c6d-8e9f-0a1b2c3d4e5f Forbidden: description: >- API access is not configured for the account, or avatar creation is disabled. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: forbidden message: API Avatar creation is disabled requestId: b3f0c2d1-4a5b-4c6d-8e9f-0a1b2c3d4e5f NotFound: description: The requested resource does not exist or belongs to another account. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: not_found message: Avatar job not found requestId: b3f0c2d1-4a5b-4c6d-8e9f-0a1b2c3d4e5f RateLimited: description: >- A rate limit, rolling 24-hour quota, or concurrency limit was exceeded. Back off and retry. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: rate_limit_exceeded message: Open API rate limit exceeded requestId: b3f0c2d1-4a5b-4c6d-8e9f-0a1b2c3d4e5f InternalError: description: An unexpected server error occurred. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: internal_error message: An internal error occurred. requestId: b3f0c2d1-4a5b-4c6d-8e9f-0a1b2c3d4e5f securitySchemes: AppId: type: apiKey in: header name: X-App-ID description: Your Spatius App ID. ApiKey: type: apiKey in: header name: X-API-Key description: The API key bound to the App ID. ````