---
title: "List all segmentation jobs"
method: GET
path: "/segments"
tags: ["Segments"]
---

# List all segmentation jobs

`GET /segments`

## Request

- Base URL: `https://api.cloudglue.dev/v1`
- URL: `https://api.cloudglue.dev/v1/segments`
- Auth: HTTP bearer

List all segmentation jobs with optional filtering

## Query parameters

- `limit` integer
- `offset` integer
- `status` 'pending' | 'processing' | 'completed' | 'failed'
- `criteria` 'shot' | 'narrative'
- `created_before` string, date
- `created_after` string, date
- `url` string

## Response `200`

A list of segmentation jobs

- SegmentsList
  - `object` 'list', required: Object type, always 'list'
  - `data` SegmentsListItem[], required: Array of segmentation job objects (without segments array or total_segments)
    - `job_id` string, uuid, required: Unique identifier for the segment job
    - `file_id` string, uuid, required: ID of the file this segment belongs to
    - `object` 'segments', required: Object type, always 'segments'
    - `status` 'pending' | 'processing' | 'completed' | 'failed', required: Current status of the segment job
    - `criteria` 'shot' | 'narrative', required: Segment criteria used for this job
    - `created_at` integer, required: Unix timestamp in milliseconds when the job was created
    - `shot_config` ShotConfig
      - `detector` 'content' | 'adaptive': Detection algorithm: • **adaptive**: Designed for dynamic footage with camera movement and action (default) • **content**: Optimized for controlled footage with clear visual transitions
      - `max_duration_seconds` number: Maximum duration for each segment in seconds (1 second to 10 minutes, default: 5 minutes)
      - `min_duration_seconds` number: Minimum duration for each segment in seconds (0.6 seconds to 10 minutes, default: 0.6 seconds)
      - `fill_gaps` boolean: When true, gaps between detected shots are filled: gaps greater than or equal to min_duration_seconds become their own segments (split by max_duration_seconds if needed), and shorter gaps are merged into the nearest adjacent segment. Defaults to true.
    - `narrative_config` NarrativeConfig
      - `prompt` string: Optional custom prompt to guide the narrative segmentation analysis. This will be incorporated into the main segmentation prompt as additional guidance.
      - `strategy` 'comprehensive' | 'balanced' | 'transcript': Narrative segmentation strategy: • **comprehensive**: Uses a VLM to deeply analyze logical segments of video. Only available for video files (not YouTube or audio). • **balanced** (default): Balanced analysis approach using multiple modalities. Supports YouTube URLs and audio files. • **transcript**: Cheap and fast speech-transcript-based segmentation. Requires a transcript; returns an error for silent or visual-only content (use `balanced` instead, or `comprehensive` for non-YouTube/non-audio video files). **Note**: YouTube URLs and audio files only support the **balanced** and **transcript** strategies; **comprehensive** will be rejected with an error.
      - `number_of_chapters` integer: Optional target number of chapters to generate. If provided, min_chapters and max_chapters will be calculated automatically if not specified. If only target is provided, the AI will attempt to generate exactly this number of chapters.
      - `min_chapters` integer: Optional minimum number of chapters to generate. If provided along with number_of_chapters and max_chapters, validates that min <= number_of_chapters <= max. If only number_of_chapters is provided, min and max are calculated automatically.
      - `max_chapters` integer: Optional maximum number of chapters to generate. If provided along with number_of_chapters and min_chapters, validates that min <= number_of_chapters <= max. If only number_of_chapters is provided, min and max are calculated automatically.
  - `total` integer, required: Total number of segmentation jobs 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

- `400`: Invalid request parameters
- `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 `400` status
  - added the optional property `code` to the response with the `500` status
- **2026-06-12** `f90a8032c6ae`: 3 breaking
  - the `data/items/shot_config/min_duration_seconds` response property's min was decreased from `1.00` to `0.60` for the response status `200`
  - the `data/items/shot_config/max_duration_seconds` response's property type changed from `integer` to `number` for status `200`
  - the `data/items/shot_config/min_duration_seconds` response's property type changed from `integer` to `number` for status `200`
- **2026-04-27** `43191ed5a246`: 1 warning
  - added the new `transcript` enum value to the `data/items/narrative_config/strategy` response property for the response status `200`
- **2026-03-11** `1d5d6115c0d0`: 2 breaking, 5 info
  - for the `query` request parameter `limit`, default value `50` was removed
  - for the `query` request parameter `offset`, default value `0` was removed
  - the `detector` response's property default value `adaptive` was removed for the status `200`
  - the `fill_gaps` response's property default value `true` was removed for the status `200`
  - …3 more
- **2026-03-09** `3700d31a3ff8`: 1 info
  - added the optional property `data/items/shot_config/fill_gaps` to the response with the `200` status

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