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

# Get project status

> Poll this after calling `POST /v1/projects/{projectId}/process`.

Returns the project status and the current state of every image in the project.
The project moves to `completed` once all jobs finish.

**Polling tip:** check `project.status` — when it's `completed` all images are done.
Individual images may still be `processing` while `project.status` is `processing`.




## OpenAPI

````yaml GET /v1/projects/{projectId}
openapi: 3.1.0
info:
  title: Fotolabs API
  version: 1.0.0
  description: >
    Programmatic access to the Fotolabs image processing pipeline.


    **Base URL:** `https://api.fotolabs.co` (prod) ·
    `https://api-staging.fotolabs.co` (staging)


    **Authentication:** Pass your API key as a Bearer token on every request.

    ```

    Authorization: Bearer fl_<key>

    ```


    **Typical flow:**

    1. `POST /v1/projects` — create a project

    2. `POST /v1/images/upload-url` + `PUT <uploadUrl>` — repeat for each image
    (no grouping needed)

    3. `POST /v1/projects/{projectId}/process` — process the whole project in
    one call

    4. `GET /v1/projects/{projectId}` — poll until `status` is `completed`;
    response includes all images and their result URLs


    **Project lifecycle:** `pending` → `processing` → `completed`

    - Images can only be uploaded to a `pending` project.

    - Processing can only be triggered on a `pending` project.

    - Once processing starts the project is locked — create a new project for
    additional images.


    **Plans:**

    - `free` — API access blocked.

    - `essential` / `ultimate` (PAYG) — charged once per project at the plan
    rate.

    - `essential_monthly` / `ultimate_monthly` — deducts one listing from your
    monthly quota; overage rate applies if quota is exhausted.
servers:
  - url: https://api.fotolabs.co
    description: Production
  - url: https://api-staging.fotolabs.co
    description: Staging
security:
  - ApiKeyAuth: []
paths:
  /v1/projects/{projectId}:
    get:
      summary: Get project status and all image results
      description: >
        Poll this after calling `POST /v1/projects/{projectId}/process`.


        Returns the project status and the current state of every image in the
        project.

        The project moves to `completed` once all jobs finish.


        **Polling tip:** check `project.status` — when it's `completed` all
        images are done.

        Individual images may still be `processing` while `project.status` is
        `processing`.
      operationId: getProject
      parameters:
        - name: projectId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          example: ca5f09f7-6838-459c-ac0f-7be03c60de24
      responses:
        '200':
          description: Project and image statuses.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectStatus'
              example:
                projectId: ca5f09f7-6838-459c-ac0f-7be03c60de24
                status: completed
                images:
                  - imageId: aaa-...
                    status: completed
                    resultImageUrl: >-
                      https://d1i1ga8jkrbik1.cloudfront.net/.../result/aaa-....jpg
                    originalImageUrl: https://d1i1ga8jkrbik1.cloudfront.net/...
                    errorMessage: null
                    createdAt: '2026-05-09T18:00:48.421Z'
                    updatedAt: '2026-05-09T18:06:00.240Z'
                  - imageId: bbb-...
                    status: failed
                    resultImageUrl: null
                    originalImageUrl: https://d1i1ga8jkrbik1.cloudfront.net/...
                    errorMessage: Gemini API quota exceeded after 5 retries
                    createdAt: '2026-05-09T18:00:50.000Z'
                    updatedAt: '2026-05-09T18:07:00.000Z'
        '401':
          description: Invalid or missing API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Project not found or belongs to a different workspace.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: Project not found or access denied
components:
  schemas:
    ProjectStatus:
      type: object
      required:
        - projectId
        - status
        - images
      properties:
        projectId:
          type: string
          format: uuid
        status:
          type: string
          enum:
            - pending
            - processing
            - completed
        images:
          type: array
          items:
            $ref: '#/components/schemas/ImageStatus'
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: string
          example: >-
            No payment method on file. Please add one at fotolabs.co before
            processing images.
    ImageStatus:
      type: object
      required:
        - imageId
        - status
        - resultImageUrl
        - originalImageUrl
        - errorMessage
        - createdAt
        - updatedAt
      properties:
        imageId:
          type: string
          format: uuid
        status:
          type: string
          enum:
            - pending
            - processing
            - completed
            - failed
        resultImageUrl:
          type: string
          format: uri
          nullable: true
          description: >-
            CloudFront URL of the processed JPEG. Non-null only when `status` is
            `completed`.
        originalImageUrl:
          type: string
          format: uri
          description: CloudFront URL of the original uploaded image.
        errorMessage:
          type: string
          nullable: true
          description: Human-readable error. Non-null only when `status` is `failed`.
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
  securitySchemes:
    ApiKeyAuth:
      type: http
      scheme: bearer
      description: API key with `fl_` prefix, issued from the Fotolabs dashboard

````