> ## 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. # List Avatar jobs > Returns the Avatar creation jobs submitted by the authenticated account, newest first. Use the `statuses` query parameter to filter by job status. ## OpenAPI ````yaml /openapi/avatar-open-api.json get /avatar-jobs 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: get: tags: - Avatar Jobs summary: List Avatar jobs description: >- Returns the Avatar creation jobs submitted by the authenticated account, newest first. Use the `statuses` query parameter to filter by job status. operationId: listAvatarJobs parameters: - name: statuses in: query required: false description: >- Repeatable status filter. Only jobs in one of the given statuses are returned. style: form explode: true schema: type: array items: $ref: '#/components/schemas/JobStatus' - $ref: '#/components/parameters/PageSize' - $ref: '#/components/parameters/PageToken' responses: '200': description: A page of Avatar creation jobs. content: application/json: schema: $ref: '#/components/schemas/ListAvatarJobsResponse' example: jobs: - 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' pagination: nextPageToken: '' totalCount: 1 '400': $ref: '#/components/responses/InvalidRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' components: schemas: JobStatus: type: string description: Lifecycle status of an Avatar creation job. enum: - queued - processing - succeeded - failed ListAvatarJobsResponse: type: object properties: jobs: type: array items: $ref: '#/components/schemas/AvatarJob' pagination: $ref: '#/components/schemas/Pagination' 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`. Pagination: type: object properties: nextPageToken: type: string description: >- Pass as `pagination.pageToken` to fetch the next page. Empty when no more pages exist. totalCount: type: integer format: int32 description: Total number of matching items. 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. 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. parameters: PageSize: name: pagination.pageSize in: query required: false description: >- Maximum number of items to return. Defaults to 20; the maximum is 99. A value above 99 falls back to the default of 20 rather than being capped, so request at most 99. schema: type: integer format: int32 default: 20 maximum: 99 minimum: 1 PageToken: name: pagination.pageToken in: query required: false description: >- Opaque token from the previous page's `nextPageToken`. Omit for the first page. Pass back exactly what the previous response returned rather than constructing a value. A token is only valid for the `pagination.pageSize` it was issued with; keep that value stable while paging, or start again from the first page. schema: type: string 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 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. ````