---
title: "Create a new extract job"
method: POST
path: "/extract"
tags: ["Extract"]
---

# Create a new extract job

`POST /extract`

## Request

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

Extract structured data from a video

## Request body

- NewExtract
  - `url` string, required: Input media URL. Supports URIs of files uploaded to Cloudglue Files endpoint, public YouTube video URLs, public TikTok video URLs, public Loom share URLs, public HTTP URLs (including direct image URLs such as JPEG/PNG/WebP), and files which have been granted access to Cloudglue via data connectors. Note that YouTube videos are currently limited to speech level understanding only. Public TikTok video URLs will be scraped and stored automatically — subject to charges. For files via our Data connectors, see our documentation on data connectors for setup information.
  - `prompt` string: A natural language prompt describing the data you want to extract. Required if no schema is provided.
  - `schema` object: A more rigid structure if you already know the JSON layout you want. Required if no prompt is provided.
  - `enable_video_level_entities` boolean: Whether to extract entities at the video level. Mutually exclusive with enable_segment_level_entities - only one can be true.
  - `enable_segment_level_entities` boolean: Whether to extract entities at the segment level. Mutually exclusive with enable_video_level_entities - only one can be true.
  - `enable_transcript_mode` boolean: When enabled, extract entities from transcript only (similar to YouTube path). Useful for speech-heavy content.
  - `enable_metadata_mode` boolean: When enabled, extract entities from the file's metadata document (filename, file details, user metadata, and connector source metadata) instead of the media content. File-level entities only; flat 1 credit per file; works on metadata-only files without ingesting their media. Mutually exclusive with enable_transcript_mode.
  - `thumbnails_config` ThumbnailsConfig
    - `enable_segment_thumbnails` boolean, required: Whether to enable segment thumbnails. If not provided will use default to false. Cannot be used together with segmentation_id.
  - `include_chapters` boolean: Include narrative chapters in the response when segmentation strategy is 'narrative'. Only affects cached completed results; newly created pending jobs do not include chapters.
  - `include_shots` boolean: Include shot boundaries in the response when segmentation strategy is 'shot-detector'. Only affects cached completed results; newly created pending jobs do not include shots.
  - `segmentation_id` string, uuid: Segmentation job id to use. If not provided will use default to uniform 20s segmentation. Cannot be provided together with segmentation_config.
  - `segmentation_config` SegmentationConfig: Configuration for video segmentation. **Choose a strategy and provide ONLY the corresponding config:** • **uniform**: Provide `uniform_config`, do NOT provide other configs • **shot-detector**: Provide `shot_detector_config`, do NOT provide other configs • **manual**: Provide `manual_config`, do NOT provide other configs • **narrative**: Provide `narrative_config`, do NOT provide other configs Optionally specify `start_time_seconds` and `end_time_seconds` to limit segmentation to a portion of the video.
    - `strategy` 'uniform' | 'shot-detector' | 'manual' | 'narrative', required: Segmentation strategy - determines which config you must provide
    - `uniform_config` SegmentationUniformConfig
      - `window_seconds` number, required: The duration of each segment in seconds. Must be between 1 and 120 seconds.
      - `hop_seconds` number: The offset between the start of new windows. This means there can be overlap between segments. If not provided, defaults to window_seconds. Must be between 1 and 120 seconds.
    - `shot_detector_config` SegmentationShotDetectorConfig
      - `threshold` number, nullable: Detection sensitivity threshold - lower values create more segments: • **content**: Sensitivity to visual differences (default: 27.0). Lower values detect smaller changes in color/lighting. • **adaptive**: Does not support threshold parameter - uses internal adaptive algorithm.
      - `min_seconds` number, nullable: The minimum length of a shot in seconds. Defaults to 0.6.
      - `max_seconds` number, nullable: The maximum length of a shot in seconds. Defaults to 300.
      - `detector` 'adaptive' | 'content', required: The detector strategy to use: • **adaptive**: Designed for dynamic footage with camera movement, panning, or action. Examples: sports broadcasts, drone footage, handheld documentaries, action movies, live events. • **content**: Optimized for controlled footage with clear visual transitions. Examples: studio interviews, corporate videos, educational content, product demos, scripted content.
      - `fill_gaps` boolean: When true, gaps between detected shots are filled: gaps greater than or equal to min_seconds become their own segments (split by max_seconds if needed), and shorter gaps are merged into the nearest adjacent segment. Defaults to true.
    - `manual_config` SegmentationManualConfig
      - `segments` object[], required: Array of segments
        - `start_time` number: The start time of the segment in seconds
        - `end_time` number: The end time of the segment in seconds
    - `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.
    - `keyframe_config` KeyframeConfig: Configuration for keyframe extraction. When provided, will be used to extract keyframes for the segmentation. This is not supported for YouTube videos.
      - `frames_per_segment` number, required: The number of key frames to extract per segment
      - `max_width` number: The maximum width of the key frames in pixels
    - `start_time_seconds` number: Optional: The start time of the video in seconds to start segmenting from
    - `end_time_seconds` number: Optional: The end time of the video in seconds to stop segmenting at

## Response `200`

Successful response

- Extract
  - `job_id` string, required
  - `status` 'pending' | 'processing' | 'completed' | 'failed' | 'not_applicable', required
  - `url` string: The URL of the processed video
  - `created_at` integer: Unix timestamp in milliseconds when the job was created
  - `extract_config` object: Configuration for automatic entity extraction from videos
    - `prompt` string: A natural language prompt describing the data to extract. Required if no schema is provided.
    - `schema` object: A more rigid structure if you already know the JSON layout you want. Required if no prompt is provided.
    - `enable_video_level_entities` boolean: Whether to extract entities at the video level. Mutually exclusive with enable_segment_level_entities - only one can be true.
    - `enable_segment_level_entities` boolean: Whether to extract entities at the segment level. Mutually exclusive with enable_video_level_entities - only one can be true.
    - `enable_transcript_mode` boolean: When enabled, extract entities from transcript only (similar to YouTube path). Useful for speech-heavy content.
    - `enable_metadata_mode` boolean: When enabled, extract entities from the file's metadata document (filename, file details, user metadata, and connector source metadata) instead of the media content. File-level entities only; flat 1 credit per file; works on metadata-only files without ingesting their media. Mutually exclusive with enable_transcript_mode.
  - `segmentation_id` string: The ID of the segmentation job used for this extraction
  - `data` object: The structured data extracted from the video based on prompt or schema. Only present when status is 'completed'.
    - `entities` object: Entities extracted from the video level
    - `segment_entities` object[]: 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.
    - `thumbnail_url` string, uri: URL of the file-level thumbnail for the video. Only present when include_thumbnails=true.
  - `total` integer: Total number of segment entities available. Only present when status is 'completed'.
  - `limit` integer: Maximum number of segment entities returned per request. Only present when status is 'completed'.
  - `offset` integer: Number of segment entities skipped. Only present when status is 'completed'.
  - `error` string: Error message if status is 'failed'
  - `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`: Invalid request or missing required prompt/schema
- `403`: Usage limit reached (monthly extract jobs, or the file limits when given a new URL) — `code: usage_limit_reached`
- `404`: Extract job not found
- `500`: An unexpected error occurred on the server

## Changes

- **2026-10-30** `23d3f240819f`: 5 info
  - added the non-success response with the status `403`
  - removed the non-success response with the status `429`
  - added the optional property `code` to the response with the `400` status
  - added the optional property `code` to the response with the `404` status
  - …1 more
- **2026-07-24** `915ee485b763`: 2 info
  - added the new optional request property `allOf[subschema #1]/enable_metadata_mode`
  - added the optional property `extract_config/enable_metadata_mode` to the response with the `200` status
- **2026-06-12** `f90a8032c6ae`: 1 info
  - the `allOf[#/components/schemas/FileSegmentationConfig]/segmentation_config/shot_detector_config/min_seconds` request property's min was decreased from `1.00` to `0.60`
- **2026-04-27** `43191ed5a246`: 1 info
  - added the new `transcript` enum value to the request property `allOf[#/components/schemas/FileSegmentationConfig]/segmentation_config/narrative_config/strategy`
- **2026-03-11** `1d5d6115c0d0`: 17 info
  - added the new optional request property `allOf[subschema #1]/include_chapters`
  - added the new optional request property `allOf[subschema #1]/include_shots`
  - the `enable_segment_level_entities` request property default value `true` was removed
  - the `enable_transcript_mode` request property default value `false` was removed
  - …13 more

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