> ## 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 pre-tests

> Lists the pre-tests of your workspace, newest first, including the ones created in the app. Results are paginated with a cursor.

Requires the `pretests:read` scope.



## OpenAPI

````yaml /api-reference/openapi.json get /pretests
openapi: 3.1.0
info:
  title: Unite API
  version: 1.0.0
  description: >-
    Run ad pre-tests from your own systems: upload a creative, create a
    pre-test, and read its result and PDF report. 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.
  - name: Pretests
    description: Create pre-tests and read their results.
  - name: Quota
    description: How many pre-tests you can still run.
  - name: Webhooks
    description: Manage the endpoints that are notified when a pre-test changes.
paths:
  /pretests:
    get:
      tags:
        - Pretests
      summary: List pre-tests
      description: >-
        Lists the pre-tests of your workspace, newest first, including the ones
        created in the app. Results are paginated with a cursor.


        Requires the `pretests:read` scope.
      operationId: listPretests
      parameters:
        - name: limit
          in: query
          required: false
          description: Page size.
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
        - name: cursor
          in: query
          required: false
          description: The nextCursor of the previous page.
          schema:
            type: string
        - name: status
          in: query
          required: false
          description: Return only pre-tests in this status.
          schema:
            type: string
            enum:
              - queued
              - processing
              - completed
              - failed
        - name: channel
          in: query
          required: false
          description: Return only pre-tests of this channel.
          schema:
            type: string
            enum:
              - ooh
              - digital
              - email
      responses:
        '200':
          description: A page of pre-tests.
          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/PretestList'
        '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 contact support. 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:
    PretestList:
      type: object
      properties:
        object:
          type: string
          const: list
        data:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              object:
                type: string
                const: pretest
              status:
                type: string
                enum:
                  - queued
                  - processing
                  - completed
                  - failed
              channel:
                type: string
                enum:
                  - ooh
                  - digital
                  - email
              title:
                type: string
              score:
                type:
                  - number
                  - 'null'
              recommendation:
                anyOf:
                  - type: string
                    enum:
                      - launch
                      - optimize
                      - iterate
                  - type: 'null'
              createdAt:
                type: string
                description: ISO 8601 UTC.
              updatedAt:
                type: string
                description: ISO 8601 UTC.
            required:
              - id
              - object
              - status
              - channel
              - title
              - score
              - recommendation
              - createdAt
              - updatedAt
        nextCursor:
          description: Pass it as cursor to get the next page. Null on the last page.
          type:
            - string
            - 'null'
      required:
        - object
        - data
        - nextCursor
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              enum:
                - invalid_api_key
                - api_key_revoked
                - api_key_expired
                - insufficient_scope
                - 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
                - invalid_ooh_format
                - invalid_placement
                - brand_not_found
                - quota_exhausted
                - not_found
                - report_not_ready
                - webhook_url_rejected
                - webhook_endpoint_limit
                - internal_error
              description: >-
                Stable machine-readable code. Branch on this, not on the
                message.
            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 contact support.
            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.

````

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