# List Thumbnails

> List Thumbnails in the authenticated Project, newest first by default.

```json
{
  "path": "/thumbnails",
  "method": "get",
  "schema": {
    "description": "List Thumbnails in the authenticated Project, newest first by default.",
    "operationId": "listThumbnails",
    "parameters": [
      {
        "description": "Maximum number of Thumbnails to return.",
        "in": "query",
        "name": "limit",
        "required": false,
        "schema": {
          "default": 100,
          "maximum": 100,
          "minimum": 1,
          "type": "integer"
        }
      },
      {
        "description": "Number of Thumbnails to skip.",
        "in": "query",
        "name": "offset",
        "required": false,
        "schema": {
          "default": 0,
          "minimum": 0,
          "type": "integer"
        }
      },
      {
        "description": "Id filters by an exact Thumbnail ID. Omit to include all matching resources.",
        "in": "query",
        "name": "id",
        "required": false,
        "schema": {
          "maxLength": 64,
          "minLength": 1,
          "type": "string"
        }
      },
      {
        "description": "Filter by Thumbnail status.",
        "in": "query",
        "name": "status",
        "required": false,
        "schema": {
          "$ref": "#/components/schemas/ThumbnailStatus"
        }
      },
      {
        "description": "Filter Thumbnails linked to this Source. Omit to include Thumbnails from all Sources in the Project.",
        "in": "query",
        "name": "source_id",
        "required": false,
        "schema": {
          "maxLength": 64,
          "minLength": 1,
          "type": "string"
        }
      },
      {
        "description": "Filter by output Storage ID.",
        "in": "query",
        "name": "storage_id",
        "required": false,
        "schema": {
          "maxLength": 64,
          "minLength": 1,
          "type": "string"
        }
      },
      {
        "description": "Created at or after this Unix timestamp in seconds.",
        "in": "query",
        "name": "created.gte",
        "required": false,
        "schema": {
          "maximum": 253402300799,
          "minimum": 0,
          "type": "integer"
        }
      },
      {
        "description": "Created at or before this Unix timestamp in seconds.",
        "in": "query",
        "name": "created.lte",
        "required": false,
        "schema": {
          "maximum": 253402300799,
          "minimum": 0,
          "type": "integer"
        }
      },
      {
        "description": "Creation-time ordering. Defaults to newest first.",
        "in": "query",
        "name": "created.sort",
        "required": false,
        "schema": {
          "default": "desc",
          "enum": [
            "asc",
            "desc"
          ],
          "type": "string"
        }
      }
    ],
    "responses": {
      "200": {
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ThumbnailListResponse",
              "examples": [
                {
                  "data": [
                    {
                      "asset_id": null,
                      "created_at": "2026-10-19T10:00:00Z",
                      "files": [],
                      "id": "thm_example",
                      "metadata": {},
                      "samples": [],
                      "settings": {
                        "count": 10,
                        "format": "jpeg",
                        "output": "images",
                        "range": {
                          "end": 60,
                          "start": 0
                        },
                        "size": 320
                      },
                      "source_id": "src_example",
                      "status": "preparing",
                      "storage_id": "stor_example",
                      "storage_prefix": "videos/thumbnails/thm_example/",
                      "updated_at": "2026-10-19T10:00:00Z"
                    }
                  ],
                  "limit": 100,
                  "offset": 0,
                  "status": "success",
                  "total": 1
                }
              ]
            }
          }
        },
        "description": "List Thumbnails"
      },
      "400": {
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ResponseErrorValidation"
            }
          }
        },
        "description": "Validation error"
      },
      "401": {
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ResponseErrorAuthentication"
            }
          }
        },
        "description": "Authentication error"
      },
      "403": {
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ResponseErrorForbidden"
            }
          }
        },
        "description": "The authenticated caller cannot access these thumbnails."
      },
      "404": {
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ResponseErrorNotFound"
            }
          }
        },
        "description": "NotFound error"
      },
      "429": {
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ResponseErrorTooManyRequests"
            }
          }
        },
        "description": "The request rate limit has been reached."
      },
      "500": {
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ResponseErrorUnexpected"
            }
          }
        },
        "description": "Unexpected error"
      }
    },
    "security": [
      {
        "ProjectAccessToken": []
      }
    ],
    "summary": "List Thumbnails",
    "tags": [
      "Thumbnails"
    ],
    "x-codeSamples": [
      {
        "lang": "typescript",
        "source": "import Chunkify from '@chunkify/chunkify';\n\nconst client = new Chunkify({\n  projectAccessToken: 'My Project Access Token',\n});\n\n// Automatically fetches more pages as needed.\nfor await (const thumbnail of client.thumbnails.list()) {\n  console.log(thumbnail.id);\n}"
      },
      {
        "lang": "python",
        "source": "from chunkify import Chunkify\n\nclient = Chunkify(\n    project_access_token=\"My Project Access Token\",\n)\n\n# Automatically fetches more pages as needed.\nfor thumbnail in client.thumbnails.list():\n    print(thumbnail.id)"
      },
      {
        "lang": "php",
        "source": "\u003c?php\n\nuse Chunkify\\Client;\n\n$client = new Client(\n    projectAccessToken: 'My Project Access Token',\n);\n\n// Automatically fetches more pages as needed.\nforeach ($client-\u003ethumbnails-\u003elist()-\u003epagingEachItem() as $thumbnail) {\n    var_dump($thumbnail-\u003eid);\n}"
      },
      {
        "lang": "golang",
        "source": "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/chunkifydev/chunkify-go\"\n\t\"github.com/chunkifydev/chunkify-go/option\"\n)\n\nfunc main() {\n\tclient := chunkify.NewClient(\n\t\toption.WithProjectAccessToken(\"My Project Access Token\"),\n\t)\n\tpage, err := client.Thumbnails.List(\n\t\tcontext.TODO(),\n\t\tchunkify.ThumbnailListParams{},\n\t)\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfor page != nil {\n\t\tfor _, thumbnail := range page.Data {\n\t\t\tfmt.Printf(\"%+v\\n\", thumbnail.ID)\n\t\t}\n\t\tpage, err = page.GetNextPage()\n\t\tif err != nil {\n\t\t\tpanic(err.Error())\n\t\t}\n\t}\n}\n"
      }
    ]
  }
}
```



```json #/components/schemas/ResponseErrorNotFound
{
  "description": "Error response",
  "properties": {
    "error": {
      "description": "Error response details",
      "properties": {
        "code": {
          "const": 404,
          "description": "Code is the HTTP status code",
          "examples": [
            404
          ],
          "type": "integer"
        },
        "message": {
          "description": "Message is a human-readable error description",
          "examples": [
            "Ressource not found"
          ],
          "type": "string"
        },
        "type": {
          "const": "NotFoundError",
          "description": "Type indicates the error category",
          "enum": [
            "NotFoundError"
          ],
          "type": "string"
        }
      },
      "required": [
        "type",
        "code",
        "message"
      ],
      "type": "object"
    },
    "status": {
      "const": "error",
      "description": "Status indicates the response status \"error\"",
      "type": "string"
    }
  },
  "required": [
    "status",
    "error"
  ],
  "type": "object"
}
```



```json #/components/schemas/ResponseErrorTooManyRequests
{
  "description": "Error response",
  "properties": {
    "error": {
      "description": "Error response details",
      "properties": {
        "code": {
          "const": 429,
          "description": "Code is the HTTP status code",
          "examples": [
            429
          ],
          "type": "integer"
        },
        "message": {
          "description": "Message is a human-readable error description",
          "examples": [
            "Rate limit exceeded"
          ],
          "type": "string"
        },
        "type": {
          "const": "TooManyRequestsError",
          "description": "Type indicates the error category",
          "enum": [
            "TooManyRequestsError"
          ],
          "type": "string"
        }
      },
      "required": [
        "type",
        "code",
        "message"
      ],
      "type": "object"
    },
    "status": {
      "const": "error",
      "description": "Status indicates the response status \"error\"",
      "type": "string"
    }
  },
  "required": [
    "status",
    "error"
  ],
  "type": "object"
}
```



```json #/components/schemas/ResponseErrorUnexpected
{
  "description": "Unexpected preview processing or storage failure.",
  "properties": {
    "error": {
      "properties": {
        "code": {
          "const": 500,
          "type": "integer"
        },
        "message": {
          "examples": [
            "Internal server error"
          ],
          "type": "string"
        },
        "type": {
          "const": "UnexpectedError",
          "type": "string"
        }
      },
      "required": [
        "type",
        "code",
        "message"
      ],
      "type": "object"
    },
    "status": {
      "const": "error",
      "type": "string"
    }
  },
  "required": [
    "status",
    "error"
  ],
  "type": "object"
}
```



```json #/components/schemas/ThumbnailStatus
{
  "description": "Status is ready only after processing and publication finish. Temporary outputs become expired after their retention period.",
  "enum": [
    "preparing",
    "ready",
    "failed",
    "expired"
  ],
  "type": "string"
}
```



```json #/components/schemas/ThumbnailListResponse
{
  "description": "A page of thumbnail requests.",
  "properties": {
    "data": {
      "description": "Data contains the matching thumbnail requests.",
      "items": {
        "$ref": "#/components/schemas/Thumbnail"
      },
      "type": "array"
    },
    "limit": {
      "description": "Limit specifies the maximum results in this page.",
      "minimum": 0,
      "type": "integer"
    },
    "offset": {
      "description": "Offset specifies the number of matching requests skipped.",
      "minimum": 0,
      "type": "integer"
    },
    "status": {
      "const": "success",
      "description": "Status is success for a successful request.",
      "type": "string"
    },
    "total": {
      "description": "Total counts matching requests before pagination.",
      "minimum": 0,
      "type": "integer"
    }
  },
  "required": [
    "status",
    "data",
    "total",
    "limit",
    "offset"
  ],
  "type": "object"
}
```



```json #/components/schemas/Thumbnail
{
  "description": "One thumbnail generation request. At least one sample and its companion files must be published before the resource is ready.",
  "properties": {
    "asset_id": {
      "description": "AssetId identifies the owning Asset for Workflow outputs, or null for standalone requests.",
      "type": [
        "string",
        "null"
      ]
    },
    "created_at": {
      "description": "CreatedAt records when the request was accepted.",
      "format": "date-time",
      "type": "string"
    },
    "created_by_token_id": {
      "description": "CreatedByTokenId specifies the Project token used to create the resource. It remains set after the token is revoked.\nOmitted for dashboard requests, MCP OAuth connections, Workflow actions, and unknown creators.",
      "examples": [
        "tok_2G6MJiNz71bHQGNzGwKx5cJwPFS"
      ],
      "type": "string"
    },
    "created_by_user_id": {
      "description": "CreatedByUserId specifies the team member who created the resource.\nOmitted for Workflow actions, unknown creators, and deleted accounts.",
      "examples": [
        "u_2G6MJiNz71bHQGNzGwKx5cJwPFS"
      ],
      "type": "string"
    },
    "created_via": {
      "$ref": "#/components/schemas/CreatedVia"
    },
    "delete_at": {
      "description": "DeleteAt specifies when this standalone request is deleted: three days after its temporary output expires, otherwise when the team's data retention period ends, counted from when the request was accepted, and no sooner than three days after it finished. It does not delete files in customer-owned Storage. Omitted while preparing and for Asset-owned thumbnails, which follow their Asset.",
      "format": "date-time",
      "type": "string"
    },
    "error": {
      "$ref": "#/components/schemas/ThumbnailError",
      "description": "Error explains a failed request. Omitted otherwise."
    },
    "expires_at": {
      "description": "ExpiresAt specifies when temporary output files expire. Omitted for customer output Storage.",
      "format": "date-time",
      "type": "string"
    },
    "files": {
      "description": "Files contains all published images or sheets and the WebVTT index. Empty while preparing.",
      "items": {
        "$ref": "#/components/schemas/ThumbnailFile"
      },
      "type": "array"
    },
    "id": {
      "description": "Id identifies this thumbnail request. Standalone requests use thm_ IDs; Asset-owned outputs use aop_ IDs.",
      "examples": [
        "thm_example"
      ],
      "type": "string"
    },
    "metadata": {
      "additionalProperties": {
        "type": "string"
      },
      "description": "Metadata contains the accepted string metadata.",
      "type": "object"
    },
    "ready_at": {
      "description": "ReadyAt records when the complete available set was published. Omitted before publication.",
      "format": "date-time",
      "type": "string"
    },
    "samples": {
      "description": "Samples contains published thumbnails ordered by timestamp. Empty while preparing. A ready resource may contain fewer samples than requested.",
      "items": {
        "$ref": "#/components/schemas/ThumbnailSample"
      },
      "type": "array"
    },
    "settings": {
      "$ref": "#/components/schemas/ThumbnailSettings",
      "description": "Settings contains the accepted sampling and output settings."
    },
    "source_id": {
      "description": "SourceId identifies the input Source, or null if it has been deleted.",
      "type": [
        "string",
        "null"
      ]
    },
    "status": {
      "$ref": "#/components/schemas/ThumbnailStatus",
      "description": "Status reports processing or output expiry."
    },
    "storage_id": {
      "description": "StorageId identifies the accepted output Storage.",
      "type": "string"
    },
    "storage_path": {
      "description": "StoragePath specifies the accepted filename template relative to the Storage base_prefix, or null when Chunkify generated the file names.",
      "type": [
        "string",
        "null"
      ]
    },
    "storage_prefix": {
      "description": "StoragePrefix specifies the complete output folder saved at creation. File and sample paths are relative to this folder.",
      "type": "string"
    },
    "updated_at": {
      "description": "UpdatedAt records the last lifecycle update.",
      "format": "date-time",
      "type": "string"
    }
  },
  "required": [
    "id",
    "source_id",
    "asset_id",
    "storage_id",
    "storage_prefix",
    "storage_path",
    "settings",
    "status",
    "metadata",
    "samples",
    "files",
    "created_at",
    "updated_at"
  ],
  "type": "object"
}
```



```json #/components/schemas/CreatedVia
{
  "description": "CreatedVia specifies how the resource was created: api for API requests, dashboard for the Chunkify dashboard, mcp for MCP clients, and workflow for Workflow actions.\nOmitted when the creator is unknown.",
  "enum": [
    "api",
    "dashboard",
    "mcp",
    "workflow"
  ],
  "examples": [
    "api"
  ],
  "type": "string"
}
```



```json #/components/schemas/ThumbnailError
{
  "description": "A customer-facing processing failure.",
  "properties": {
    "code": {
      "description": "Code identifies the processing failure.",
      "type": "string"
    },
    "message": {
      "description": "Message explains the processing failure.",
      "type": "string"
    }
  },
  "required": [
    "code",
    "message"
  ],
  "type": "object"
}
```



```json #/components/schemas/ThumbnailFile
{
  "description": "One published image, sprite sheet, or WebVTT file.",
  "properties": {
    "cdn_url": {
      "description": "CdnUrl provides delivery through the configured CDN. Omitted without a CDN or after expiry.",
      "type": "string"
    },
    "height": {
      "description": "Height specifies the measured image or complete sprite canvas height. Omitted for WebVTT.",
      "minimum": 1,
      "type": "integer"
    },
    "kind": {
      "description": "Kind identifies an individual image, sprite sheet, or WebVTT index.",
      "enum": [
        "image",
        "sprite",
        "vtt"
      ],
      "type": "string"
    },
    "path": {
      "description": "Path specifies the file relative to storage_prefix.",
      "type": "string"
    },
    "size": {
      "description": "Size specifies the measured encoded file size in bytes.",
      "minimum": 1,
      "type": "integer"
    },
    "url": {
      "description": "Url provides temporary authorized delivery. Omitted after expiry or when unavailable.",
      "type": "string"
    },
    "width": {
      "description": "Width specifies the measured image or complete sprite canvas width. Omitted for WebVTT.",
      "minimum": 1,
      "type": "integer"
    }
  },
  "required": [
    "path",
    "kind",
    "size"
  ],
  "type": "object"
}
```



```json #/components/schemas/ThumbnailSample
{
  "description": "One successfully published requested sample. Repeated samples remain separate entries.",
  "properties": {
    "crop": {
      "$ref": "#/components/schemas/ThumbnailCrop",
      "description": "Crop specifies the tile origin in its sprite sheet. Omitted for individual images; width and height give the tile dimensions."
    },
    "height": {
      "description": "Height specifies this image or tile height in pixels.",
      "minimum": 1,
      "type": "integer"
    },
    "path": {
      "description": "Path identifies the image or sprite sheet in files.",
      "type": "string"
    },
    "timestamp": {
      "description": "Timestamp specifies the measured Source-relative presentation time of the selected frame in seconds. Compatible cached inputs use millisecond timestamps, which can select a neighboring frame compared with the original Source.",
      "minimum": 0,
      "type": "number"
    },
    "width": {
      "description": "Width specifies this image or tile width in pixels.",
      "minimum": 1,
      "type": "integer"
    }
  },
  "required": [
    "timestamp",
    "path",
    "width",
    "height"
  ],
  "type": "object"
}
```



```json #/components/schemas/ThumbnailCrop
{
  "description": "The image rectangle within a sprite sheet.",
  "properties": {
    "x": {
      "description": "X specifies the left edge in pixels.",
      "minimum": 0,
      "type": "integer"
    },
    "y": {
      "description": "Y specifies the top edge in pixels.",
      "minimum": 0,
      "type": "integer"
    }
  },
  "required": [
    "x",
    "y"
  ],
  "type": "object"
}
```



```json #/components/schemas/ThumbnailSettings
{
  "description": "Accepted sampling and output settings, with defaults resolved.",
  "oneOf": [
    {
      "required": [
        "timestamps"
      ]
    },
    {
      "required": [
        "count"
      ]
    }
  ],
  "properties": {
    "count": {
      "description": "Count specifies 1 to 100 thumbnails at the middle of equal sections of the selected range.",
      "maximum": 100,
      "minimum": 1,
      "type": "integer"
    },
    "format": {
      "$ref": "#/components/schemas/ThumbnailFormat",
      "description": "Format specifies the accepted image encoding."
    },
    "output": {
      "$ref": "#/components/schemas/ThumbnailOutput",
      "description": "Output specifies the accepted output mode."
    },
    "range": {
      "$ref": "#/components/schemas/ThumbnailRange",
      "description": "Range contains the accepted sampling boundaries."
    },
    "size": {
      "description": "Size specifies the accepted maximum image or tile edge in pixels.",
      "maximum": 1920,
      "minimum": 64,
      "type": "integer"
    },
    "timestamps": {
      "description": "Timestamps specifies 1 to 100 Source-relative target times in seconds. Every time must be within the selected range. Repeated targets produce separate outputs.",
      "items": {
        "description": "A target time in seconds.",
        "minimum": 0,
        "type": "number"
      },
      "maxItems": 100,
      "minItems": 1,
      "type": "array"
    }
  },
  "required": [
    "range",
    "output",
    "format",
    "size"
  ],
  "type": "object"
}
```



```json #/components/schemas/ThumbnailFormat
{
  "description": "Format specifies the image encoding.",
  "enum": [
    "jpeg",
    "webp"
  ],
  "type": "string"
}
```



```json #/components/schemas/ThumbnailOutput
{
  "description": "Output specifies individual images or automatically arranged sprite sheets.",
  "enum": [
    "images",
    "sprites"
  ],
  "type": "string"
}
```



```json #/components/schemas/ThumbnailRange
{
  "description": "The resolved Source-relative sampling range.",
  "properties": {
    "end": {
      "description": "End specifies the exclusive upper bound in seconds.",
      "exclusiveMinimum": 0,
      "type": "number"
    },
    "start": {
      "description": "Start specifies the inclusive lower bound in seconds.",
      "minimum": 0,
      "type": "number"
    }
  },
  "required": [
    "start",
    "end"
  ],
  "type": "object"
}
```



```json #/components/schemas/ThumbnailStatus
{
  "description": "Status is ready only after processing and publication finish. Temporary outputs become expired after their retention period.",
  "enum": [
    "preparing",
    "ready",
    "failed",
    "expired"
  ],
  "type": "string"
}
```



```json #/components/schemas/ResponseErrorValidation
{
  "properties": {
    "error": {
      "properties": {
        "code": {
          "const": 400,
          "description": "Code is the HTTP status code",
          "examples": [
            400
          ],
          "type": "integer"
        },
        "message": {
          "description": "Message is a human-readable error description",
          "examples": [
            "Invalid request parameters"
          ],
          "type": "string"
        },
        "type": {
          "const": "ValidationError",
          "description": "Type indicates the error category",
          "enum": [
            "ValidationError"
          ],
          "type": "string"
        }
      },
      "required": [
        "type",
        "code",
        "message"
      ],
      "type": "object"
    },
    "status": {
      "const": "error",
      "description": "Status indicates the response status \"error\"",
      "type": "string"
    }
  },
  "required": [
    "status",
    "error"
  ]
}
```



```json #/components/schemas/ResponseErrorAuthentication
{
  "description": "Error response",
  "properties": {
    "error": {
      "description": "Error response details",
      "properties": {
        "code": {
          "const": 401,
          "description": "Code is the HTTP status code",
          "examples": [
            401
          ],
          "type": "integer"
        },
        "message": {
          "description": "Message is a human-readable error description",
          "examples": [
            "Authentication error: invalid token or subscription inactive"
          ],
          "type": "string"
        },
        "type": {
          "const": "AuthenticationError",
          "description": "Type indicates the error category",
          "enum": [
            "AuthenticationError"
          ],
          "type": "string"
        }
      },
      "required": [
        "type",
        "code",
        "message"
      ],
      "type": "object"
    },
    "status": {
      "const": "error",
      "description": "Status indicates the response status \"error\"",
      "type": "string"
    }
  },
  "required": [
    "status",
    "error"
  ],
  "type": "object"
}
```



```json #/components/schemas/ResponseErrorForbidden
{
  "properties": {
    "error": {
      "description": "Error response details",
      "properties": {
        "code": {
          "const": 403,
          "description": "Code is the HTTP status code",
          "examples": [
            403
          ],
          "type": "integer"
        },
        "message": {
          "description": "Message is a human-readable error description",
          "examples": [
            "Unauthorized to perform this action"
          ],
          "type": "string"
        },
        "type": {
          "const": "ForbiddenError",
          "description": "Type indicates the error category",
          "enum": [
            "ForbiddenError"
          ],
          "type": "string"
        }
      },
      "required": [
        "type",
        "code",
        "message"
      ],
      "type": "object"
    },
    "status": {
      "const": "error",
      "description": "Status indicates the response status \"error\"",
      "type": "string"
    }
  },
  "required": [
    "status",
    "error"
  ]
}
```