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

# List generations

> Your generations, newest first, one page at a time. While `has_more` is true, pass the last `id` of a page as `after` to get the next one.



## OpenAPI

````yaml /openapi.json get /generations
openapi: 3.1.0
info:
  title: Codzen API
  version: 1.0.0
  description: >-
    Generate video and images with every Codzen model through one asynchronous
    API.
servers:
  - url: https://codzen.ai/api/v1
security:
  - apiKey: []
paths:
  /generations:
    get:
      summary: List generations
      description: >-
        Your generations, newest first, one page at a time. While `has_more` is
        true, pass the last `id` of a page as `after` to get the next one.
      operationId: listGenerations
      parameters:
        - name: limit
          in: query
          required: false
          description: How many generations to return.
          schema:
            default: 20
            type: integer
            minimum: 1
            maximum: 100
        - name: after
          in: query
          required: false
          description: >-
            Return the generations created before this one: the last `id` of the
            previous page.
          schema:
            type: string
            pattern: ^gen_
        - name: status
          in: query
          required: false
          description: Only this status.
          schema:
            type: string
            enum:
              - queued
              - processing
              - succeeded
              - failed
        - name: model
          in: query
          required: false
          description: Only this model slug.
          schema:
            type: string
      responses:
        '200':
          description: One page of generations.
          headers:
            x-request-id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenerationList'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  headers:
    RequestId:
      description: ID of the request; quote it when contacting support.
      schema:
        type: string
    RetryAfter:
      description: Seconds to wait before retrying.
      schema:
        type: integer
        minimum: 0
  schemas:
    GenerationList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Generation'
          description: Generations, newest first.
        has_more:
          type: boolean
          description: Whether more generations follow; pass the last `id` as `after`.
      required:
        - data
        - has_more
      additionalProperties: false
      description: One page of generations.
    Generation:
      type: object
      properties:
        id:
          type: string
          pattern: ^gen_
          description: ID of the generation.
        model:
          type: string
          description: Slug of the model, as submitted.
        status:
          type: string
          enum:
            - queued
            - processing
            - succeeded
            - failed
          description: >-
            `queued` → `processing` → `succeeded` or `failed`. New values may be
            added; treat an unknown value as not finished.
        input:
          type: object
          propertyNames:
            type: string
          additionalProperties: {}
          description: >-
            The input, normalized: input assets point at Codzen copies; other
            fields are as submitted.
        outputs:
          type: array
          items:
            type: object
            properties:
              type:
                type: string
                enum:
                  - video
                  - image
                  - audio
                  - 3d
                description: Kind of media.
              url:
                type: string
                format: uri
                description: Where to download the output; no API key is needed.
            required:
              - type
              - url
            additionalProperties: false
            description: One delivered output.
          description: Delivered outputs; empty until the generation succeeds.
        cost:
          type: object
          properties:
            currency:
              type: string
              const: USD
            estimated:
              type: string
              pattern: ^-?\d+(\.\d+)?$
              description: The estimate, held from the balance at submission.
            amount:
              anyOf:
                - type: string
                  pattern: ^-?\d+(\.\d+)?$
                  description: A decimal amount in USD, as a string.
                - type: 'null'
              description: >-
                The final cost: `null` until the generation finishes, `"0.00"`
                when it fails.
            usage:
              type: array
              items:
                type: object
                properties:
                  unit:
                    type: string
                    description: >-
                      Billing unit, as the model is priced, such as
                      `output_second` or `million_tokens`.
                  quantity:
                    type: number
                    minimum: 0
                    description: Billed quantity of the unit.
                  unit_price:
                    type: string
                    pattern: ^-?\d+(\.\d+)?$
                    description: Price of one unit, in USD.
                required:
                  - unit
                  - quantity
                  - unit_price
                additionalProperties: false
                description: One price row the generation was billed by.
              description: What the final cost was computed from; empty until known.
          required:
            - currency
            - estimated
            - amount
            - usage
          additionalProperties: false
          description: What the generation costs.
        error:
          anyOf:
            - $ref: '#/components/schemas/Error'
            - type: 'null'
          description: Why the generation failed; `null` unless it failed.
        created_at:
          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: ISO 8601 time in UTC.
        started_at:
          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))$
              description: ISO 8601 time in UTC.
            - type: 'null'
          description: When processing started; `null` while queued.
        completed_at:
          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))$
              description: ISO 8601 time in UTC.
            - type: 'null'
          description: When the generation finished; `null` until then.
      required:
        - id
        - model
        - status
        - input
        - outputs
        - cost
        - error
        - created_at
        - started_at
        - completed_at
      additionalProperties: false
      description: 'One generation: a request to a model and its outputs.'
    HttpError:
      type: object
      properties:
        error:
          $ref: '#/components/schemas/Error'
        request_id:
          type: string
          description: ID of the request, also in the `x-request-id` header.
      required:
        - error
        - request_id
      additionalProperties: false
      description: Body of every error response.
    Error:
      type: object
      properties:
        type:
          type: string
          enum:
            - invalid_request_error
            - authentication_error
            - billing_error
            - permission_error
            - not_found_error
            - rate_limit_error
            - upstream_error
            - api_error
          description: Broad category of the error.
        code:
          type: string
          enum:
            - invalid_request
            - content_rejected
            - invalid_api_key
            - insufficient_balance
            - api_key_disabled
            - account_suspended
            - model_not_found
            - generation_not_found
            - rate_limited
            - concurrency_limit
            - model_unavailable
            - upstream_failed
            - timeout
            - internal_error
          description: Stable error code; branch on this, not on `message`.
        message:
          type: string
          description: Human-readable explanation; it may change at any time.
        param:
          description: The request field the error is about, such as `input.seed`.
          type: string
        stage:
          description: >-
            For `content_rejected`: whether the input or the output was
            rejected.
          type: string
          enum:
            - input
            - output
        retryable:
          type: boolean
          description: Whether sending the same request again may succeed.
      required:
        - type
        - code
        - message
        - retryable
      additionalProperties: false
      description: What went wrong.
  responses:
    BadRequest:
      description: The request is invalid (`invalid_request_error`).
      headers:
        x-request-id:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/HttpError'
    Unauthorized:
      description: The API key is missing or invalid (`authentication_error`).
      headers:
        x-request-id:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/HttpError'
    Forbidden:
      description: >-
        The API key is disabled or the account is suspended
        (`permission_error`).
      headers:
        x-request-id:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/HttpError'
    TooManyRequests:
      description: >-
        Too many requests or concurrent generations (`rate_limit_error`). Retry
        after the `Retry-After` header.
      headers:
        x-request-id:
          $ref: '#/components/headers/RequestId'
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/HttpError'
    InternalServerError:
      description: Something went wrong on our side (`api_error`). Retry later.
      headers:
        x-request-id:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/HttpError'
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: >-
        Your API key (`cz_…`), created in the console. Use it only on your
        server.

````

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