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

# Read a generation

> One generation and each output's status, asset and error. Send `Prefer: wait=N` to hold the response until it ends. Reads never start or repeat work.

Needs the `generations:read` scope.



## OpenAPI

````yaml /openapi.json get /generations/{id}
openapi: 3.1.0
info:
  title: ZeroGen API
  version: v1
  description: >-
    Generate images and video with every model in ZeroGen from your own servers.
    Generated from the API's contracts by `npm run openapi` in apps/web; do not
    edit by hand.
servers:
  - url: https://api.zerogen.com/v1
security:
  - bearerAuth: []
tags:
  - name: Account
    description: The calling key and the organization's balance.
  - name: Models
    description: The models an organization can run and their schemas.
  - name: Generations
    description: Quote, create, read, list and cancel generations.
  - name: Uploads
    description: Upload files into the Library to use as inputs.
paths:
  /generations/{id}:
    get:
      tags:
        - Generations
      summary: Read a generation
      description: >-
        One generation and each output's status, asset and error. Send `Prefer:
        wait=N` to hold the response until it ends. Reads never start or repeat
        work.


        Needs the `generations:read` scope.
      operationId: getGeneration
      parameters:
        - name: id
          in: path
          required: true
          description: The generation's ID
          schema:
            type: string
        - $ref: '#/components/parameters/Prefer'
      responses:
        '200':
          description: The generation.
          headers:
            Request-Id:
              $ref: '#/components/headers/Request-Id'
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimit-Limit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimit-Remaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimit-Reset'
            Preference-Applied:
              $ref: '#/components/headers/Preference-Applied'
            Deprecation:
              $ref: '#/components/headers/Deprecation'
            Sunset:
              $ref: '#/components/headers/Sunset'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Generation'
        '202':
          description: >-
            With `Prefer: wait`, the generation had not ended when the wait ran
            out.
          headers:
            Request-Id:
              $ref: '#/components/headers/Request-Id'
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimit-Limit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimit-Remaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimit-Reset'
            Preference-Applied:
              $ref: '#/components/headers/Preference-Applied'
            Deprecation:
              $ref: '#/components/headers/Deprecation'
            Sunset:
              $ref: '#/components/headers/Sunset'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Generation'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
components:
  parameters:
    Prefer:
      name: Prefer
      in: header
      required: false
      description: >-
        wait=N holds the response up to N seconds (at most 60) until the
        generation ends.
      schema:
        type: string
        pattern: ^wait=\d+$
        example: wait=30
  headers:
    Request-Id:
      description: Identifies the request; quote it when contacting support.
      schema:
        type: string
    RateLimit-Limit:
      description: Requests the key may make in the current window.
      schema:
        type: integer
    RateLimit-Remaining:
      description: Requests left in the current window.
      schema:
        type: integer
    RateLimit-Reset:
      description: Seconds until the current window resets.
      schema:
        type: integer
    Preference-Applied:
      description: The wait applied, such as wait=30.
      schema:
        type: string
    Deprecation:
      description: When the model was deprecated, as @ followed by Unix seconds.
      schema:
        type: string
    Sunset:
      description: When the deprecated model stops accepting requests (HTTP date).
      schema:
        type: string
    WWW-Authenticate:
      description: Bearer realm="ZeroGen API".
      schema:
        type: string
    Retry-After:
      description: Seconds to wait before retrying.
      schema:
        type: integer
  schemas:
    Generation:
      type: object
      properties:
        id:
          type: string
        projectId:
          type: string
          description: The project that holds the outputs
        model:
          anyOf:
            - type: string
              maxLength: 200
              pattern: >-
                ^[a-z0-9]+(?:[.-][a-z0-9]+)*\/[a-z0-9]+(?:[.-][a-z0-9]+)*\/[a-z0-9]+(?:[.-][a-z0-9]+)*$
            - type: 'null'
        modelVersion:
          type:
            - string
            - 'null'
        status:
          type: string
          enum:
            - queued
            - running
            - succeeded
            - partial
            - failed
            - cancelled
        outputs:
          type: array
          items:
            type: object
            properties:
              index:
                type: integer
                minimum: 0
                maximum: 9007199254740991
              status:
                type: string
                enum:
                  - queued
                  - running
                  - succeeded
                  - failed
                  - cancelled
              asset:
                anyOf:
                  - type: object
                    properties:
                      id:
                        type: string
                      mimeType:
                        type: string
                      width:
                        anyOf:
                          - type: integer
                            exclusiveMinimum: 0
                            maximum: 9007199254740991
                          - type: 'null'
                      height:
                        anyOf:
                          - type: integer
                            exclusiveMinimum: 0
                            maximum: 9007199254740991
                          - type: 'null'
                      durationMs:
                        anyOf:
                          - type: integer
                            minimum: 0
                            maximum: 9007199254740991
                          - type: 'null'
                      resourceUri:
                        type: string
                        description: >-
                          Where this transport's client reads the asset, such as
                          an MCP resource
                    required:
                      - id
                      - mimeType
                      - width
                      - height
                      - durationMs
                    additionalProperties: false
                  - type: 'null'
              error:
                anyOf:
                  - $ref: '#/components/schemas/Error'
                  - type: 'null'
              warnings:
                type: array
                items:
                  type: object
                  properties:
                    code:
                      type: string
                    message:
                      type: string
                  required:
                    - code
                    - message
                  additionalProperties: false
                description: What the provider ignored, such as an unused reference
              draft:
                type: object
                properties:
                  expiresAt:
                    type: string
                    format: date-time
                    pattern: >-
                      ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
                    description: When upscaling this output closes
                  upscalable:
                    type: boolean
                    description: >-
                      A final can be requested now: unexpired, with no final in
                      progress
                  upscale:
                    anyOf:
                      - type: string
                        enum:
                          - upscaling
                          - upscaled
                      - type: 'null'
                    description: The newest final's state, or null when none was requested
                  finalResolution:
                    type: string
                    description: >-
                      That final's resolution, one the model's draft control
                      lists
                  finalAssetId:
                    type: string
                    description: The newest finished final's asset
                required:
                  - expiresAt
                  - upscalable
                  - upscale
                additionalProperties: false
                description: >-
                  A 480p Draft output; upscaling it makes a final with the same
                  seed, at a resolution the model's draft control lists
            required:
              - index
              - status
              - asset
              - error
            additionalProperties: false
        error:
          anyOf:
            - $ref: '#/components/schemas/Error'
            - type: 'null'
        billing:
          type: object
          properties:
            mode:
              type: string
              enum:
                - platform
                - byok
                - test
            state:
              anyOf:
                - type: string
                  enum:
                    - held
                    - charged
                    - released
                - type: 'null'
              description: >-
                held: an amount is reserved and nothing is charged yet; charged:
                chargedMicroUsd is the final charge; released: the hold ended
                with no charge; null: billing never admitted the generation, so
                nothing was held or charged
            hold:
              type: object
              properties:
                state:
                  type: string
                  enum:
                    - running
                    - ended
                    - needs_attention
                  description: >-
                    running: the generation has not ended; ended: it ended and
                    the hold is still pending; needs_attention: it has stayed
                    pending 30 minutes after ending, or 24 hours after admission
                    with no end recorded (endedAt then stays null), so ZeroGen
                    is looking into it
                endedAt:
                  anyOf:
                    - type: string
                      format: date-time
                      pattern: >-
                        ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
                    - type: 'null'
                  description: >-
                    When the generation ended; null while it runs or when no end
                    was recorded
              required:
                - state
                - endedAt
              additionalProperties: false
              description: >-
                While held, where the generation stands. It reports facts, not
                what settlement will do
            quotedMicroUsd:
              anyOf:
                - type: integer
                  minimum: 0
                  maximum: 9007199254740991
                - type: 'null'
              description: Reserved maximum expected charge
            heldMicroUsd:
              anyOf:
                - type: integer
                  minimum: 0
                  maximum: 9007199254740991
                - type: 'null'
              description: While held, the amount reserved now; it is never a charge
            chargedMicroUsd:
              anyOf:
                - type: integer
                  minimum: 0
                  maximum: 9007199254740991
                - type: 'null'
              description: >-
                The final charge once charged, zero once released; it can rarely
                exceed the quote
          required:
            - mode
            - state
            - quotedMicroUsd
            - heldMicroUsd
            - chargedMicroUsd
          additionalProperties: false
        createdAt:
          type: string
          format: date-time
          pattern: >-
            ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
        startedAt:
          anyOf:
            - type: string
              format: date-time
              pattern: >-
                ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
            - type: 'null'
        finishedAt:
          anyOf:
            - type: string
              format: date-time
              pattern: >-
                ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
            - type: 'null'
      required:
        - id
        - projectId
        - model
        - modelVersion
        - status
        - outputs
        - error
        - billing
        - createdAt
        - startedAt
        - finishedAt
      additionalProperties: false
    Error:
      type: object
      properties:
        code:
          type: string
          pattern: ^[a-z][a-z0-9_]{0,79}$
        message:
          type: string
        param:
          type: string
        retryable:
          type: boolean
        details:
          type: object
          propertyNames:
            type: string
          additionalProperties: {}
      required:
        - code
        - message
        - retryable
      additionalProperties: false
    ErrorResponse:
      type: object
      properties:
        error:
          $ref: '#/components/schemas/Error'
      required:
        - error
      additionalProperties: false
  responses:
    BadRequest:
      description: >-
        The request is malformed or invalid: invalid_request, validation_failed,
        model_unavailable or input_import_failed.
      headers:
        Request-Id:
          $ref: '#/components/headers/Request-Id'
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimit-Limit'
        RateLimit-Remaining:
          $ref: '#/components/headers/RateLimit-Remaining'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimit-Reset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: 'invalid_api_key: the key is missing, revoked or expired.'
      headers:
        Request-Id:
          $ref: '#/components/headers/Request-Id'
        WWW-Authenticate:
          $ref: '#/components/headers/WWW-Authenticate'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Forbidden:
      description: >-
        permission_denied: the key lacks the scope this endpoint needs, the
        request came from a browser, or the API isn't enabled for the
        organization.
      headers:
        Request-Id:
          $ref: '#/components/headers/Request-Id'
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimit-Limit'
        RateLimit-Remaining:
          $ref: '#/components/headers/RateLimit-Remaining'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimit-Reset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: >-
        not_found: no such resource for this caller, including a projectId the
        caller can't use.
      headers:
        Request-Id:
          $ref: '#/components/headers/Request-Id'
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimit-Limit'
        RateLimit-Remaining:
          $ref: '#/components/headers/RateLimit-Remaining'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimit-Reset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    TooManyRequests:
      description: >-
        rate_limited: the key or its owner is over the rate limit, or the
        organization is at its running cap. Retry after Retry-After seconds.
      headers:
        Request-Id:
          $ref: '#/components/headers/Request-Id'
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimit-Limit'
        RateLimit-Remaining:
          $ref: '#/components/headers/RateLimit-Remaining'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimit-Reset'
        Retry-After:
          $ref: '#/components/headers/Retry-After'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    InternalError:
      description: 'internal: something went wrong. Retry.'
      headers:
        Request-Id:
          $ref: '#/components/headers/Request-Id'
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimit-Limit'
        RateLimit-Remaining:
          $ref: '#/components/headers/RateLimit-Remaining'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimit-Reset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    ServiceUnavailable:
      description: >-
        unavailable or pricing_unavailable: API keys, billing or pricing can't
        be reached right now. Retry.
      headers:
        Request-Id:
          $ref: '#/components/headers/Request-Id'
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimit-Limit'
        RateLimit-Remaining:
          $ref: '#/components/headers/RateLimit-Remaining'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimit-Reset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'A ZeroGen API key: zg_ for a live key, zg_test_ for a test key.'

````

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