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

# List jobs

> Your jobs in this workspace, newest first. Send the same filters with each page's cursor.



## OpenAPI

````yaml /openapi/voyager-api.yaml get /jobs
openapi: 3.1.0
info:
  title: Voyager API
  description: >-
    Generate images, video, speech, music, sound effects and 3D with your
    Voyager workspace's credits. Authenticate with `Authorization: Bearer
    vy_live_…`. Every response carries `X-Request-ID` and the
    `X-RateLimit-Limit` / `X-RateLimit-Remaining` / `X-RateLimit-Reset` (seconds
    until the window resets) headers; a 429 adds `Retry-After`. Errors share one
    envelope (`ErrorResponse`).
  version: 1.0.0
  x-voyager-agent-prompt: >
    Set up the Voyager API in this project.


    Voyager generates images, video, speech, music, sound effects, 3D and object
    masks with the same models

    and credits as the Voyager app. Docs: https://docs.voyager.so/api 
    (agent-readable:

    https://docs.voyager.so/llms.txt, OpenAPI:
    https://api.voyager.so/v1/openapi.json)


    1. Key: read it from the env var VOYAGER_API_KEY. Never hard-code it or
    commit it; add
       VOYAGER_API_KEY= to .env.example and make sure .env is git-ignored. If it's missing,
       ask me to create one at https://voyager.so/dashboard/api (paid plans).
    2. Base URL https://api.voyager.so/v1, header: Authorization: Bearer
    $VOYAGER_API_KEY

    3. Pick a model: GET
    /models?type=image|video|speech|music|sound_effect|3d|segment. Read
       GET /models/{id} for its input_schema before building a request.
    4. Optional cost check: POST /estimate with the same body as step 5; it
    returns
       estimated_charge (credits) and can_run.
    5. Create: POST /jobs {"model": "<id>", "operation": "<op>", "input": {...}}
    with an Idempotency-Key header
       (a new UUID per logical request; reuse it when retrying the same request).
    6. Wait: GET /jobs/{id}?wait=25 until status is succeeded, failed or
    canceled
       (honor Retry-After / poll_after_ms). Or pass "webhook_url" and verify the
       Standard Webhooks signature with the secret from the dashboard.
    7. Results: job.outputs[].url is a signed link valid for 1 hour; download it
    right
       away, or GET /jobs/{id} again for a fresh link. Files are kept 30 days.
    8. Errors are {"error": {"code","message","retryable",...}}. 402 = out of
    credits or
       not on a paid plan (show error.details.upgrade_url to me). 429 = slow down: wait
       Retry-After seconds. Retry only when retryable is true, with the same Idempotency-Key.

    Minimal example (curl):
      curl -s https://api.voyager.so/v1/jobs \
        -H "Authorization: Bearer $VOYAGER_API_KEY" -H "Content-Type: application/json" \
        -H "Idempotency-Key: $(uuidgen)" \
        -d '{"model":"nano-banana-2.1","operation":"text-to-image","input":{"prompt":"a red fox in snow","aspect_ratio":"16:9"}}'
      curl -s "https://api.voyager.so/v1/jobs/<job id>?wait=25" -H "Authorization: Bearer $VOYAGER_API_KEY"

    Write a small typed client (create → wait → download) with retries as above,
    then

    generate one test image to prove it works and tell me what it cost
    (job.credits.charged;

    if credits.state is still "pending", report job.credits.estimated and say
    it's an estimate).
servers:
  - url: https://api.voyager.so/v1
    description: Production
security: []
paths:
  /jobs:
    get:
      tags:
        - Jobs
      summary: List jobs
      description: >-
        Your jobs in this workspace, newest first. Send the same filters with
        each page's cursor.
      operationId: listJobs
      parameters:
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            maximum: 100
            minimum: 1
            default: 20
            title: Limit
        - name: cursor
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                maxLength: 400
              - type: 'null'
            description: next_cursor from the previous page.
            title: Cursor
          description: next_cursor from the previous page.
        - name: type
          in: query
          required: false
          schema:
            anyOf:
              - enum:
                  - image
                  - video
                  - speech
                  - music
                  - sound_effect
                  - 3d
                  - segment
                type: string
              - type: 'null'
            title: Type
        - name: status
          in: query
          required: false
          schema:
            anyOf:
              - enum:
                  - queued
                  - running
                  - succeeded
                  - failed
                  - canceled
                type: string
              - type: 'null'
            title: Status
        - name: created_after
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                format: date-time
              - type: 'null'
            description: Only jobs created after this instant.
            title: Created After
          description: Only jobs created after this instant.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobList'
          headers:
            X-Request-ID:
              $ref: '#/components/headers/X-Request-ID'
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          headers:
            X-Request-ID:
              $ref: '#/components/headers/X-Request-ID'
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
        '401':
          description: Missing, invalid or revoked API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          headers:
            X-Request-ID:
              $ref: '#/components/headers/X-Request-ID'
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
        '429':
          description: Rate limited. Retry after Retry-After seconds.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          headers:
            X-Request-ID:
              $ref: '#/components/headers/X-Request-ID'
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
            Retry-After:
              $ref: '#/components/headers/Retry-After'
        '503':
          description: Temporarily unavailable. Retry with backoff.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          headers:
            X-Request-ID:
              $ref: '#/components/headers/X-Request-ID'
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
      security:
        - bearerAuth: []
components:
  schemas:
    JobList:
      properties:
        object:
          type: string
          const: list
          title: Object
          default: list
          description: Always "list".
        data:
          items:
            $ref: '#/components/schemas/Job'
          type: array
          title: Data
          description: This page's items.
        has_more:
          type: boolean
          title: Has More
          description: Whether another page follows.
        next_cursor:
          anyOf:
            - type: string
            - type: 'null'
          title: Next Cursor
          description: Pass as `cursor` to read the next page; null on the last page.
      type: object
      required:
        - data
        - has_more
        - next_cursor
      title: JobList
    ErrorResponse:
      properties:
        error:
          $ref: '#/components/schemas/ErrorBody'
          description: What went wrong.
      type: object
      required:
        - error
      title: ErrorResponse
      description: Every non-2xx answer.
    Job:
      properties:
        id:
          type: string
          title: Id
          description: job_…
        object:
          type: string
          const: job
          title: Object
          default: job
          description: Always "job".
        type:
          type: string
          title: Type
          description: image, video, speech, music, sound_effect or 3d.
        model:
          anyOf:
            - type: string
            - type: 'null'
          title: Model
          description: The model that ran (or will run) the job.
        operation:
          anyOf:
            - type: string
            - type: 'null'
          title: Operation
          description: e.g. text-to-image, edit, image-to-video, tts.
        status:
          type: string
          enum:
            - queued
            - running
            - succeeded
            - failed
            - canceled
          title: Status
          description: queued, running, succeeded, failed or canceled.
        input:
          additionalProperties: true
          type: object
          title: Input
          description: The job's input, as sent.
        outputs:
          items:
            $ref: '#/components/schemas/JobOutput'
          type: array
          title: Outputs
          description: The files the job made, once it succeeded.
        credits:
          $ref: '#/components/schemas/JobCredits'
          description: What the job is expected to cost and what it was charged.
        error:
          anyOf:
            - $ref: '#/components/schemas/JobError'
            - type: 'null'
          description: Why the job failed or was canceled.
        metadata:
          additionalProperties:
            type: string
          type: object
          title: Metadata
          description: The metadata sent with the job, echoed as is.
        created_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Created At
          description: When it was created (ISO 8601).
        started_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Started At
          description: When the job started running (ISO 8601); null while queued.
        completed_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Completed At
          description: When the job reached a terminal status (ISO 8601); null until then.
        poll_after_ms:
          anyOf:
            - type: integer
            - type: 'null'
          title: Poll After Ms
          description: 'While active: when to poll again.'
        links:
          $ref: '#/components/schemas/JobLinks'
          description: Links to read and cancel the job.
        cast_usage:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Cast Usage
          description: >-
            Jobs created with X-Voyager-Cast-Version: 1 and input.cast: what the
            Elements compiled to (strategy, card versions, sent and omitted
            photos, warnings). Absent on every other job.
      type: object
      required:
        - id
        - type
        - model
        - operation
        - status
        - input
        - outputs
        - credits
        - error
        - metadata
        - created_at
        - started_at
        - completed_at
        - poll_after_ms
        - links
      title: Job
    ErrorBody:
      properties:
        type:
          $ref: '#/components/schemas/ErrorType'
          description: Stable category to branch on.
        code:
          type: string
          enum:
            - invalid_request
            - invalid_input
            - content_policy
            - upstream_unavailable
            - rate_limited
            - queue_full
            - model_unavailable
            - model_not_found
            - insufficient_credits
            - paid_plan_required
            - model_not_in_plan
            - model_access_required
            - outcome_unknown
            - expired
            - not_found
            - conflict
            - forbidden
            - internal_error
            - catalog_unavailable
            - billing_unavailable
            - no_voyager_seat
            - credits_reloading
            - cast_not_supported
            - voice_cloning_unavailable
            - too_many_references
            - payload_too_large
            - upload_too_large
            - intake_full
            - invalid_url
            - fetch_failed
            - unsupported_file
            - invalid_api_key
            - idempotency_conflict
            - idempotency_in_flight
            - invalid_idempotency_key
            - invalid_cursor
            - invalid_webhook_url
            - method_not_allowed
            - account_unavailable
            - plan_required_for_faces
            - version_conflict
            - slug_taken
            - already_referenced
            - asset_in_use
            - upload_incomplete
            - cancel_unsupported
            - unsupported_model
            - invalid_job_id
            - voice_required
            - observation_timeout
            - reference_unavailable
            - queue_timeout
            - reference_missing
          title: Code
          description: >-
            Stable machine code; never renamed once published (x-voyager-errors
            lists each).
        message:
          type: string
          title: Message
          description: For developers. Not localized.
        doc_url:
          type: string
          title: Doc Url
          description: https://docs.voyager.so/api/errors#<code>
        request_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Request Id
          description: Also in the X-Request-ID header; quote it to support.
        retryable:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Retryable
          description: Whether the same request can succeed later.
        retry_after_ms:
          anyOf:
            - type: integer
            - type: 'null'
          title: Retry After Ms
          description: How long to wait before retrying.
        param:
          anyOf:
            - type: string
            - type: 'null'
          title: Param
          description: >-
            The request field at fault, as a path (e.g. input.resolution); set
            on invalid_input.
        details:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Details
          description: Code-specific detail, e.g. upgrade_url on a billing wall.
      type: object
      required:
        - type
        - code
        - message
        - doc_url
      title: ErrorBody
    JobOutput:
      properties:
        id:
          type: string
          title: Id
          description: file_… id; GET /v1/files/{id} for a fresh link.
        object:
          type: string
          const: file
          title: Object
          default: file
          description: Always "file".
        type:
          type: string
          title: Type
          description: image, video, audio, model3d or other.
        mime_type:
          type: string
          title: Mime Type
          description: The file's media type, e.g. image/png or video/mp4.
        file_name:
          type: string
          title: File Name
          description: The file's name.
        size_bytes:
          type: integer
          title: Size Bytes
          description: Size in bytes.
        url:
          type: string
          title: Url
          description: Signed download link, valid one hour.
        url_expires_at:
          type: string
          format: date-time
          title: Url Expires At
          description: >-
            When `url` stops working (ISO 8601); read the object again for a
            fresh link.
        expires_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Expires At
          description: When the file itself is deleted (outputs are kept 30 days).
        width:
          anyOf:
            - type: integer
            - type: 'null'
          title: Width
          description: Width in pixels, when known.
        height:
          anyOf:
            - type: integer
            - type: 'null'
          title: Height
          description: Height in pixels, when known.
        duration_seconds:
          anyOf:
            - type: number
            - type: 'null'
          title: Duration Seconds
          description: Length in seconds, when known.
        formats:
          anyOf:
            - items:
                $ref: '#/components/schemas/JobOutputFormat'
              type: array
            - type: 'null'
          title: Formats
          description: '3D jobs: every downloadable format.'
        preview_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Preview Url
          description: '3D jobs: a still preview.'
        role:
          anyOf:
            - type: string
            - type: 'null'
          title: Role
          description: >-
            What the file is beside the main output: mask, cutout, mask_video,
            data or preview (segmentation).
        metadata:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Metadata
          description: >-
            Per-file facts: a mask's object_id, score and box (source pixels), a
            mask video's frames.
      type: object
      required:
        - id
        - type
        - mime_type
        - file_name
        - size_bytes
        - url
        - url_expires_at
        - expires_at
      title: JobOutput
    JobCredits:
      properties:
        estimated:
          anyOf:
            - type: number
            - type: 'null'
          title: Estimated
          description: Estimated charge when the job is accepted. Not a cap.
        held:
          anyOf:
            - type: number
            - type: 'null'
          title: Held
          description: Credits held for this job now, where proven; null when unknown.
        charged:
          anyOf:
            - type: number
            - type: 'null'
          title: Charged
          description: Final charge once settled; null until then (never a stand-in zero).
        released:
          anyOf:
            - type: number
            - type: 'null'
          title: Released
          description: Held credits returned, where proven; null when unknown.
        state:
          type: string
          enum:
            - pending
            - settled
            - unresolved
          title: State
          description: >-
            pending: the final charge may still arrive; settled: final;
            unresolved: this API will not state it (see your usage), or the
            job's outcome could not be proven.
        charge_ref:
          anyOf:
            - type: string
            - type: 'null'
          title: Charge Ref
          description: The charge reference in your usage records; quote it to support.
      type: object
      required:
        - estimated
        - held
        - charged
        - released
        - state
        - charge_ref
      title: JobCredits
    JobError:
      properties:
        code:
          type: string
          title: Code
          description: A stable machine code (see x-voyager-errors).
        message:
          type: string
          title: Message
          description: For developers. Not localized.
        details:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Details
          description: Code-specific detail.
      type: object
      required:
        - code
        - message
      title: JobError
    JobLinks:
      properties:
        self:
          type: string
          title: Self
          description: GET this job.
        cancel:
          type: string
          title: Cancel
          description: POST here to cancel the job.
      type: object
      required:
        - self
        - cancel
      title: JobLinks
    ErrorType:
      type: string
      enum:
        - invalid_request
        - authentication
        - permission
        - not_found
        - conflict
        - rate_limited
        - idempotency_conflict
        - unprocessable
        - upstream_error
        - internal_error
      title: ErrorType
      description: Closed set of high-level categories SDKs branch on.
    JobOutputFormat:
      properties:
        format:
          type: string
          title: Format
          description: glb, fbx, usdz, obj or ply.
        id:
          type: string
          title: Id
          description: The format's id.
        url:
          type: string
          title: Url
          description: A link to the file in this format.
        url_expires_at:
          type: string
          format: date-time
          title: Url Expires At
          description: >-
            When `url` stops working (ISO 8601); read the object again for a
            fresh link.
      type: object
      required:
        - format
        - id
        - url
        - url_expires_at
      title: JobOutputFormat
  headers:
    X-Request-ID:
      description: This request's id (also error.request_id).
      schema:
        type: string
    X-RateLimit-Limit:
      description: >-
        Requests allowed per 60 seconds in this bucket (120 writes or 600 reads
        per minute per key).
      schema:
        type: integer
    X-RateLimit-Remaining:
      description: Requests left in this window.
      schema:
        type: integer
    X-RateLimit-Reset:
      description: Seconds until the window resets.
      schema:
        type: integer
    Retry-After:
      description: Seconds to wait before retrying.
      schema:
        type: integer
  securitySchemes:
    bearerAuth:
      type: http
      description: A Voyager API key from https://voyager.so/dashboard/api.
      scheme: bearer
      bearerFormat: vy_live_…

````

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