---
title: "Retrieve extracted entities for a specific file in a collection"
method: GET
path: "/collections/{collection_id}/videos/{file_id}/entities"
tags: ["Collections"]
---

# Retrieve extracted entities for a specific file in a collection

`GET /collections/{collection_id}/videos/{file_id}/entities`

## Request

- Base URL: `https://api.cloudglue.dev/v1`
- URL: `https://api.cloudglue.dev/v1/collections/{collection_id}/videos/{file_id}/entities`
- Auth: HTTP bearer

Retrieve extracted entities for a specific file in a collection. Results are paginated with a default limit of 50 segment entities per request (maximum 100). Use limit and offset parameters to paginate through all results. This API is only available when the collection is created with collection_type 'entities'

## Path parameters

- `collection_id` string, required
- `file_id` string, required

## Query parameters

- `limit` integer
- `offset` integer
- `include_thumbnails` boolean
- `include_chapters` boolean
- `include_shots` boolean

## Response `200`

File entities

- FileEntities
  - `collection_id` string, required: ID of the collection
  - `file_id` string, required: ID of the file
  - `thumbnail_url` string, uri: URL of the file-level thumbnail for the video. Only present when include_thumbnails=true.
  - `entities` object, required: Entities extracted from the file at the video level
  - `segment_entities` object[], required: Array of video entities extracted from individual time segments
    - `start_time` number: Start time of the segment in seconds
    - `end_time` number: End time of the segment in seconds
    - `entities` object: Entities extracted from the segment
    - `thumbnail_url` string, uri: URL of the segment thumbnail, when available.
  - `total` integer, required: Total number of segment entities available
  - `limit` integer, required: Maximum number of entities returned per request
  - `offset` integer, required: Number of entities skipped
  - `chapters` object[]: Array of narrative chapters (only present when include_chapters=true and segmentation strategy is 'narrative')
    - `index` integer, required
    - `start_time` number, required
    - `end_time` number, required
    - `description` string, required
  - `shots` object[]: Array of shot boundaries (only present when include_shots=true and segmentation strategy is 'shot-detector')
    - `index` integer, required
    - `start_time` number, required
    - `end_time` number, required
  - `total_chapters` integer: Total number of chapters (only present when include_chapters=true and segmentation strategy is 'narrative')
  - `total_shots` integer: Total number of shots (only present when include_shots=true and segmentation strategy is 'shot-detector')

## Other responses

- `400`: Collection type is not 'entities'
- `404`: Collection or file not found
- `500`: An unexpected error occurred on the server

## Changes

- **2026-10-30** `23d3f240819f`: 3 info
  - added the optional property `code` to the response with the `400` status
  - 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`: 3 breaking, 6 info
  - for the `query` request parameter `include_thumbnails`, default value `false` was removed
  - for the `query` request parameter `limit`, default value `50` was removed
  - for the `query` request parameter `offset`, default value `0` was removed
  - added the new optional `query` request parameter `include_chapters`
  - …5 more
- **2026-03-09** `3700d31a3ff8`: 3 info
  - added the new optional `query` request parameter `include_thumbnails`
  - added the optional property `segment_entities/items/thumbnail_url` to the response with the `200` status
  - added the optional property `thumbnail_url` to the response with the `200` status
- **2025-10-16** `e2dce1715ffc`: 6 info
  - added the new optional `query` request parameter `limit`
  - added the new optional `query` request parameter `offset`
  - the response property `segment_entities` became required for the status `200`
  - added the required property `limit` to the response with the `200` status
  - …2 more

[Operation history](https://skmtc.dev/cloudglue/apis/cloudglue-api/changes/collections/:collection_id/videos/:file_id/entities/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)