---
title: "List frame extractions for a file"
method: GET
path: "/files/{file_id}/frames"
tags: ["Files"]
---

# List frame extractions for a file

`GET /files/{file_id}/frames`

## Request

- Base URL: `https://api.cloudglue.dev/v1`
- URL: `https://api.cloudglue.dev/v1/files/{file_id}/frames`
- Auth: HTTP bearer

List all frame extractions for a specific file

## Path parameters

- `file_id` string, uuid, required

## Query parameters

- `limit` integer
- `offset` integer

## Response `200`

List of frame extractions

- FrameExtractionList
  - `object` 'list', required: Object type, always 'list'
  - `data` object[], required: Array of frame extraction objects
    - `frame_extraction_id` string, uuid, required: Unique identifier for the frame extraction job
    - `status` 'pending' | 'processing' | 'completed' | 'failed', required: Status of the frame extraction job
    - `created_at` number, required: Unix timestamp in milliseconds when the frame extraction was created
    - `file_id` string, uuid, required: ID of the file this frame extraction belongs to
    - `frame_extraction_config` FrameExtractionConfig, required: Configuration for frame extraction. Currently only supports uniform strategy.
      - `strategy` 'uniform', required: Frame extraction strategy - currently only 'uniform' is supported
      - `uniform_config` FrameExtractionUniformConfig: Configuration for uniform frame extraction
        - `frames_per_second` number: Number of frames to extract per second of video
        - `max_width` number: Maximum width of extracted frames in pixels. Aspect ratio is preserved.
      - `thumbnails_config` FrameExtractionThumbnailsConfig: Configuration for frame thumbnails
        - `enable_frame_thumbnails` boolean: Whether to generate CDN-hosted thumbnails for extracted frames
      - `start_time_seconds` number: Optional: The start time of the video in seconds to start extracting frames from
      - `end_time_seconds` number: Optional: The end time of the video in seconds to stop extracting frames at
    - `frame_count` number: Total number of frames extracted (only present when status is completed)
  - `total` integer, required: Total number of frame extractions matching the query
  - `limit` integer, required: Number of items returned in this response
  - `offset` integer, required: Offset from the start of the list

## Other responses

- `404`: File not found
- `500`: An unexpected error occurred on the server

## Changes

- **2026-10-30** `23d3f240819f`: 2 info
  - added the optional property `code` to the response with the `404` status
  - added the optional property `code` to the response with the `500` status
- **2026-03-11** `1d5d6115c0d0`: 2 breaking, 3 info
  - for the `query` request parameter `limit`, default value `50` was removed
  - for the `query` request parameter `offset`, default value `0` was removed
  - the `enable_frame_thumbnails` response's property default value `true` was removed for the status `200`
  - the `frames_per_second` response's property default value `1` was removed for the status `200`
  - …1 more
- **2025-10-10** `98ab592d7867`: 1 breaking
  - the response property `data/items/frame_extraction_config/thumbnails_config/enable_frame_thumbnails` became optional for the status `200`
- **2025-10-10** `3f3c2cfec49d`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/cloudglue/apis/cloudglue-api/changes/files/:file_id/frames/get.md)

---

[API](https://skmtc.dev/cloudglue/apis/cloudglue-api.md) - [All operations](https://skmtc.dev/cloudglue/apis/cloudglue-api/llms.txt) - [OpenAPI document](https://skmtc.dev/cloudglue/apis/cloudglue-api/revisions/23d3f240819f?raw)