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

# List generations, or read several by id

> Lists the workspace's generations, newest first, made in the app or through the API, paged with limit and nextCursor. With ids (up to 12, comma-separated) it returns those in that order and waitSeconds (up to 40) waits until all end; an id the workspace lacks comes back as not_found in its place. ids cannot be combined with mediaType, status, limit or cursor. The workspace must have generation enabled (public_create): otherwise 403 feature_not_enabled.

Requires the `create:read` scope.



## OpenAPI

````yaml /api-reference/openapi.json get /create/generations
openapi: 3.1.0
info:
  title: Unite API
  version: 1.0.0
  description: >-
    Run Ad Score pre-tests from your own systems: upload a creative, create a
    pre-test, and read its result and PDF report. The Ad Score routes are under
    /adscore and need the adscore:read or adscore:write scope; uploads and
    webhook endpoints are shared by every product and stay at the root. Every
    request needs an API key sent as a Bearer token. Every response carries an
    X-Request-Id header.
servers:
  - url: https://myunite.ai/api/v1
security:
  - bearerAuth: []
tags:
  - name: Catalog
    description: What you can send when you create a pre-test.
  - name: Uploads
    description: Send creative files and brand assets.
  - name: Brands
    description: Create and complete brands for your workspace.
  - name: Pretests
    description: Create pre-tests and read their results.
  - name: Quota
    description: How many pre-tests you can still run.
  - name: Create
    description: Generate and edit images, videos and music, and read what was generated.
  - name: Webhooks
    description: Manage the endpoints that are notified when a pre-test changes.
paths:
  /create/generations:
    get:
      tags:
        - Create
      summary: List generations, or read several by id
      description: >-
        Lists the workspace's generations, newest first, made in the app or
        through the API, paged with limit and nextCursor. With ids (up to 12,
        comma-separated) it returns those in that order and waitSeconds (up to
        40) waits until all end; an id the workspace lacks comes back as
        not_found in its place. ids cannot be combined with mediaType, status,
        limit or cursor. The workspace must have generation enabled
        (public_create): otherwise 403 feature_not_enabled.


        Requires the `create:read` scope.
      operationId: listCreateGenerations
      parameters:
        - name: ids
          in: query
          required: false
          description: Up to 12 generation ids, comma-separated.
          schema:
            type: string
        - name: waitSeconds
          in: query
          required: false
          description: With ids, wait up to this long while they run.
          schema:
            type: integer
            minimum: 0
            maximum: 40
        - name: mediaType
          in: query
          required: false
          description: Only this media type.
          schema:
            type: string
            enum:
              - image
              - video
              - audio
        - name: status
          in: query
          required: false
          description: Only this status.
          schema:
            type: string
            enum:
              - queued
              - generating
              - completed
              - failed
        - name: limit
          in: query
          required: false
          description: Page size (default 20).
          schema:
            type: integer
            minimum: 1
            maximum: 50
        - name: cursor
          in: query
          required: false
          description: The nextCursor of the previous page.
          schema:
            type: string
      responses:
        '200':
          description: A page of generations, or the ones asked by ids.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-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/GenerationList'
        '401':
          description: >-
            Error. Possible codes: invalid_api_key, api_key_revoked,
            api_key_expired.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: >-
            Error. Possible codes: feature_not_enabled, key_owner_not_member,
            insufficient_scope.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: 'Error. Possible codes: invalid_request.'
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-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/Error'
        '429':
          description: 'Error. Possible codes: rate_limited.'
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-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/Error'
        '500':
          description: 'Error. Possible codes: internal_error.'
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-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/Error'
components:
  headers:
    X-Request-Id:
      description: >-
        Identifier of this request. Quote it when you email support@myunite.ai.
        It is also in error.requestId.
      schema:
        type: string
    RateLimit-Limit:
      description: >-
        Requests allowed per minute for this key and bucket: 600 for reads, 60
        for writes. Sent on responses once the key is accepted. On 401 errors
        and on 403 errors raised while the key is checked they may be absent.
      schema:
        type: integer
    RateLimit-Remaining:
      description: Requests left in the current window.
      schema:
        type: integer
    RateLimit-Reset:
      description: Seconds until the oldest counted request leaves the window.
      schema:
        type: integer
    Retry-After:
      description: Seconds to wait before you try again.
      schema:
        type: integer
  schemas:
    GenerationList:
      type: object
      properties:
        generations:
          type: array
          items:
            anyOf:
              - type: object
                properties:
                  id:
                    type: string
                    description: gen_ followed by the generation id.
                  status:
                    type: string
                    enum:
                      - queued
                      - generating
                      - completed
                      - failed
                  mediaType:
                    type: string
                    enum:
                      - image
                      - video
                      - audio
                  model:
                    type: object
                    properties:
                      id:
                        type: string
                      name:
                        type: string
                    required:
                      - id
                      - name
                  prompt:
                    description: Only when one generation is read, never in a list.
                    type: string
                  createdAt:
                    type: string
                    description: ISO 8601 UTC.
                  completedAt:
                    description: ISO 8601 UTC. Null until the generation ends.
                    type:
                      - string
                      - 'null'
                  cost:
                    type: object
                    properties:
                      estimatedCredits:
                        type:
                          - number
                          - 'null'
                      chargedCredits:
                        description: Null while the charge is still settling.
                        type:
                          - number
                          - 'null'
                      refunded:
                        type: boolean
                      refundedCredits:
                        description: >-
                          When only part of the generation is refunded (formats
                          that failed), the credits refunded or being refunded.
                        type: number
                    required:
                      - estimatedCredits
                      - chargedCredits
                      - refunded
                  outputs:
                    type: array
                    items:
                      type: object
                      properties:
                        url:
                          type: string
                        thumbnailUrl:
                          type:
                            - string
                            - 'null'
                        mimeType:
                          type:
                            - string
                            - 'null'
                        width:
                          type:
                            - number
                            - 'null'
                        height:
                          type:
                            - number
                            - 'null'
                        durationSeconds:
                          type:
                            - number
                            - 'null'
                        format:
                          description: >-
                            When one piece was adapted to several formats, the
                            WxH format of this file.
                          type: string
                        ref:
                          description: >-
                            When the generation has several files, this one as a
                            media argument: gen_<id>#<n>, n counted from 1 in
                            outputs.
                          type: string
                      required:
                        - url
                        - thumbnailUrl
                        - mimeType
                        - width
                        - height
                        - durationSeconds
                  error:
                    anyOf:
                      - type: object
                        properties:
                          code:
                            type: string
                            enum:
                              - content_rejected
                              - cancelled
                              - system_failure
                              - generation_failed
                          message:
                            type: string
                        required:
                          - code
                          - message
                      - type: 'null'
                  videoEditId:
                    description: The edit this video came from; its cost is the edit's.
                    type: string
                required:
                  - id
                  - status
                  - mediaType
                  - model
                  - createdAt
                  - completedAt
                  - cost
                  - outputs
                  - error
              - type: object
                properties:
                  id:
                    type: string
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: not_found
                    required:
                      - code
                required:
                  - id
                  - error
        nextCursor:
          type:
            - string
            - 'null'
        pollAfterSeconds:
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
      required:
        - generations
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              enum:
                - invalid_api_key
                - api_key_revoked
                - api_key_expired
                - insufficient_scope
                - insufficient_role
                - confirmation_required
                - content_rejected
                - insufficient_credits
                - spend_limit_reached
                - feature_not_enabled
                - key_owner_not_member
                - rate_limited
                - concurrency_limit
                - invalid_request
                - idempotency_key_required
                - idempotency_conflict
                - idempotency_key_retired
                - upload_not_found
                - upload_invalid
                - file_too_large
                - video_too_long
                - source_url_rejected
                - source_url_unreachable
                - invalid_ooh_format
                - voice_origin_mismatch
                - invalid_placement
                - brand_not_found
                - quota_exhausted
                - not_found
                - report_not_ready
                - pretest_in_progress
                - webhook_url_rejected
                - webhook_endpoint_limit
                - internal_error
              description: >-
                Stable machine-readable code. Branch on this, not on the
                message. voice_origin_mismatch is legacy: no longer returned.
            message:
              type: string
              description: Human-readable explanation in English. Its wording can change.
            requestId:
              type: string
              description: >-
                Same value as the X-Request-Id response header. Quote it when
                you email support@myunite.ai.
            docUrl:
              type: string
              description: Page that explains this code.
            param:
              description: >-
                The field, query parameter or header the error refers to, when
                there is one.
              type: string
          required:
            - code
            - message
            - requestId
            - docUrl
      required:
        - error
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        API key, sent as `Authorization: Bearer unite_live_...`. Create keys in
        the workspace settings.

````

## Related topics

- [List the models of every generation operation](https://docs.myunite.ai/api-reference/create/list-the-models-of-every-generation-operation.md)
- [Get a generation](https://docs.myunite.ai/api-reference/create/get-a-generation.md)
- [Generate or edit an image, a video or music, or quote it](https://docs.myunite.ai/api-reference/create/generate-or-edit-an-image-a-video-or-music-or-quote-it.md)
- [MCP para agentes de IA](https://docs.myunite.ai/mcp-server.md)
- [List pre-tests](https://docs.myunite.ai/api-reference/pretests/list-pre-tests.md)


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