> ## Documentation Index > Fetch the complete documentation index at: https://docs.cloudglue.dev/llms.txt > Use this file to discover all available pages before exploring further. # List Media Descriptions > List all media description jobs with optional filtering ## OpenAPI ````yaml GET /describe openapi: 3.0.0 info: title: Cloudglue API description: API for Cloudglue license: name: Apache License 2.0 url: https://www.apache.org/licenses/LICENSE-2.0 version: 0.7.11 servers: - url: https://api.cloudglue.dev/v1 security: - bearerAuth: [] paths: /describe: get: tags: - Describe summary: List all media description jobs description: List all media description jobs with optional filtering operationId: listDescribes parameters: - name: limit in: query description: Maximum number of description jobs to return required: false schema: type: integer maximum: 100 - name: offset in: query description: Number of description jobs to skip required: false schema: type: integer - name: status in: query description: Filter description jobs by status required: false schema: type: string enum: - pending - processing - completed - failed - not_applicable - name: created_before in: query description: >- Filter description jobs created before a specific date (YYYY-MM-DD format), in UTC timezone required: false schema: type: string format: date - name: created_after in: query description: >- Filter description jobs created after a specific date (YYYY-MM-DD format), in UTC timezone required: false schema: type: string format: date - name: url in: query description: Filter description jobs by the input URL used for description required: false schema: type: string - name: response_format in: query description: Format for the response required: false schema: type: string enum: - json - markdown - name: include_data in: query description: >- Include the data in the response. If false, the response will only include the job information and not the data to minimize the response size. required: false schema: type: boolean - name: modalities in: query required: false schema: $ref: '#/components/schemas/ModalitiesSchema' - name: include_metadata in: query description: >- Include the file's user-defined metadata and source metadata. In markdown these render as a `## Metadata` section; in JSON they populate `file.metadata` and `file.source_metadata`. required: false schema: type: boolean default: false responses: '200': description: A list of description jobs content: application/json: schema: $ref: '#/components/schemas/DescribeList' '400': description: Invalid request parameters content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: An unexpected error occurred on the server content: application/json: schema: $ref: '#/components/schemas/Error' components: schemas: ModalitiesSchema: type: array items: type: string enum: - speech - visual_scene_description - scene_text - audio_description - summary - segment_summary - title description: >- The modalities to output in the response. Can be used to return smaller data sets. Comma separated list of strings. Defaults to all modalities available / previously extracted. Accepted values are speech,visual_scene_description,scene_text, audio_description, summary, segment_summary, title DescribeList: type: object properties: object: type: string enum: - list description: Object type, always 'list' data: type: array items: $ref: '#/components/schemas/Describe' description: Array of describe job objects total: type: integer description: Total number of describe jobs matching the query limit: type: integer description: Number of items returned in this response offset: type: integer description: Offset from the start of the list required: - object - data - total - limit - offset Error: required: - error type: object properties: error: type: string Describe: required: - job_id - status type: object properties: job_id: type: string status: type: string enum: - pending - processing - completed - failed - not_applicable url: type: string description: The URL of the processed video duration_seconds: type: number description: Duration of the video in seconds thumbnail_url: type: string format: uri description: >- URL of the file-level thumbnail for the video. Only present when include_thumbnails=true. created_at: type: integer description: Unix timestamp in milliseconds when the job was created describe_config: type: object description: Configuration for media description from videos properties: enable_summary: type: boolean description: >- Whether the user requested to generate video-level and segment-level (moment-level) summaries and titles enable_speech: type: boolean description: Whether the user requested to generate speech transcript enable_visual_scene_description: type: boolean description: Whether the user requested to generate visual scene description enable_scene_text: type: boolean description: Whether the user requested to generate scene text enable_audio_description: type: boolean description: Whether the user requested to generate audio description participants: type: array maxItems: 50 description: >- Known participants on the recording. When provided, speaker naming is constrained to these people: transcript speaker labels will only use one of these names (or a generic "Speaker N"), never an invented name. Intended for uploaded files, which (unlike data-connector files such as Grain) carry no participant metadata; for connector files this is populated automatically and need not be supplied. items: type: object required: - name properties: name: type: string description: Participant display name, e.g. "Alice Smith". scope: type: string description: >- Optional free-form context for the participant, e.g. a role, affiliation, or "internal"/"external". Used only as naming context. use_in_default_index: type: boolean description: >- Whether this describe job's search documents are included in the default index. data: allOf: - type: object properties: content: type: string description: >- Content string returned based on formatting, e.g. set to markdown text when response_format=markdown is requested title: type: string description: >- Generated title of the video; for YouTube videos, this is the title of the video as it appears on YouTube summary: type: string description: >- Generated video level summary; for YouTube videos, this is the summary of the video as it appears on YouTube segment_summary: type: array description: >- Array of summary information for each segment of the video. Only available when enable_summary is set to true in the describe configuration. items: type: object properties: title: type: string description: Generated segment-level title summary: type: string description: Generated segment-level summary start_time: type: number description: Start time of segment in seconds end_time: type: number description: End time of segment in seconds thumbnail_url: type: string format: uri description: URL of the segment thumbnail, when available. - $ref: '#/components/schemas/DescribeOutput' error: type: string description: Error message if status is 'failed' segmentation_id: type: string format: uuid description: >- The ID of the segmentation job if the describe was run with a segmentation chapters: type: array description: >- Array of narrative chapters (only present when include_chapters=true and segmentation strategy is 'narrative') items: type: object properties: index: type: integer minimum: 0 start_time: type: number minimum: 0 end_time: type: number minimum: 0 description: type: string required: - index - start_time - end_time - description shots: type: array description: >- Array of shot boundaries (only present when include_shots=true and segmentation strategy is 'shot-detector') items: type: object properties: index: type: integer minimum: 0 start_time: type: number minimum: 0 end_time: type: number minimum: 0 required: - index - start_time - end_time total_chapters: type: integer minimum: 0 description: >- Total number of chapters (only present when include_chapters=true and segmentation strategy is 'narrative') total_shots: type: integer minimum: 0 description: >- Total number of shots (only present when include_shots=true and segmentation strategy is 'shot-detector') file: allOf: - $ref: '#/components/schemas/File' description: >- The file this document describes. `metadata` and `source_metadata` are only included when `include_metadata` is true. DescribeOutput: type: object properties: visual_scene_description: type: array description: Array of visual descriptions items: $ref: '#/components/schemas/DescribeOutputPart' scene_text: type: array description: Array of scene text extractions items: $ref: '#/components/schemas/DescribeOutputPart' speech: type: array description: Array of speech transcriptions items: $ref: '#/components/schemas/SpeechOutputPart' audio_description: type: array description: Array of audio descriptions items: $ref: '#/components/schemas/DescribeOutputPart' File: type: object properties: id: type: string description: Unique identifier for the file status: type: string enum: - pending - processing - completed - failed - not_applicable description: Processing status of the file bytes: type: integer nullable: true description: Size of the file in bytes, null if not available created_at: type: integer description: Unix timestamp in milliseconds when the file was created filename: type: string description: Original filename uri: type: string description: Cloudglue URI for the file, to be used in other API calls metadata: type: object nullable: true description: User-provided metadata about the file, null if none provided media_type: type: string enum: - video - audio - image description: >- Type of media file (video, audio, or image). Images are processed at the file level only (no segmentation). media_info: type: object properties: duration_seconds: type: number nullable: true description: Duration in seconds width: type: integer nullable: true description: Width in pixels (null for audio files) height: type: integer nullable: true description: Height in pixels (null for audio files) sample_rate: type: integer nullable: true description: Audio sample rate in Hz channels: type: integer nullable: true description: Number of audio channels bitrate: type: integer nullable: true description: Audio bitrate in bps format: type: string nullable: true description: File format has_audio: type: boolean nullable: true description: Whether the file has audio description: Unified media information for video, audio, and image files video_info: type: object properties: duration_seconds: type: number nullable: true description: Duration of the video in seconds, null if not available height: type: integer nullable: true description: Height of the video in pixels, null if not available width: type: integer nullable: true description: Width of the video in pixels, null if not available format: type: string nullable: true description: Format of the video file, null if not available has_audio: type: boolean nullable: true description: Whether the video has audio, null if not available description: Information about the video content thumbnail_url: type: string description: URL of the thumbnail for the file source: type: string enum: - video - youtube - s3 - dropbox - http - upload - google-drive - zoom - gong - recall - gcs - grain - loom - iconik description: Source of the file source_metadata: allOf: - $ref: '#/components/schemas/SourceMetadata' nullable: true description: >- Source provenance captured from the upstream connector at ingest time. Null when nothing was captured (older files, or a connector that does not yet populate it). required: - id - uri - status DescribeOutputPart: type: object properties: text: type: string description: Text content start_time: type: number description: Start time in seconds end_time: type: number description: End time in seconds SpeechOutputPart: type: object properties: speaker: type: string description: Identified speaker text: type: string description: Transcribed speech text start_time: type: number description: Start time of speech in seconds end_time: type: number description: End time of speech in seconds words: type: array description: >- Word-level timestamps. Only present when include_word_timestamps=true. Not available for YouTube sources. items: $ref: '#/components/schemas/WordTimestamp' SourceMetadata: oneOf: - $ref: '#/components/schemas/GrainSourceMetadata' - $ref: '#/components/schemas/ZoomSourceMetadata' - $ref: '#/components/schemas/RecallSourceMetadata' - $ref: '#/components/schemas/GoogleDriveSourceMetadata' - $ref: '#/components/schemas/DropboxSourceMetadata' - $ref: '#/components/schemas/GongSourceMetadata' - $ref: '#/components/schemas/IconikSourceMetadata' discriminator: propertyName: source_type mapping: grain: $ref: '#/components/schemas/GrainSourceMetadata' zoom: $ref: '#/components/schemas/ZoomSourceMetadata' recall: $ref: '#/components/schemas/RecallSourceMetadata' google-drive: $ref: '#/components/schemas/GoogleDriveSourceMetadata' dropbox: $ref: '#/components/schemas/DropboxSourceMetadata' gong: $ref: '#/components/schemas/GongSourceMetadata' iconik: $ref: '#/components/schemas/IconikSourceMetadata' description: >- Per-source provenance captured from the upstream connector, discriminated by source_type. Populated for Grain, Zoom, Recall, Google Drive, Dropbox, Gong, and iconik; files synced before a connector was upgraded carry null. S3/GCS files carry null (plain object stores have no richer metadata). WordTimestamp: type: object description: A single word with its timing information properties: word: type: string description: The word text start_time: type: number description: Start time of the word in seconds end_time: type: number description: End time of the word in seconds required: - word - start_time - end_time GrainSourceMetadata: type: object description: >- Source provenance captured from Grain at ingest time. The richer AI/contextual fields are only present when Grain returns them. properties: source_type: type: string enum: - grain description: Discriminator identifying the upstream connector. grain_recording_id: type: string description: Grain's recording id. title: type: string description: Recording title. nullable: true start_datetime: type: string format: date-time description: UTC time Grain started the recording. nullable: true end_datetime: type: string format: date-time description: UTC time the recording ended. nullable: true duration_ms: type: integer description: Recording duration in milliseconds. nullable: true media_type: type: string enum: - audio - transcript - video description: Grain media type of the recording. nullable: true upstream_source: type: string enum: - aircall - local_capture - meet - teams - upload - webex - zoom - other description: Platform Grain captured the recording from. nullable: true grain_url: type: string description: URL to the recording in Grain. nullable: true thumbnail_url: type: string nullable: true description: Thumbnail URL, null if none. tags: type: array items: type: string description: Tags applied to the recording. nullable: true teams: type: array items: type: object properties: id: type: string name: type: string description: Teams the recording belongs to. nullable: true meeting_type: type: object nullable: true properties: id: type: string name: type: string scope: type: string description: Recording's meeting type, null if none. participants: type: array items: type: object properties: id: type: string name: type: string email: type: string nullable: true scope: type: string enum: - internal - external - unknown confirmed_attendee: type: boolean hs_contact_id: type: string nullable: true description: HubSpot contact id, if linked. nullable: true description: >- Meeting participants (include-gated by Grain). Null when requested but empty. highlights: type: array items: type: object nullable: true description: Clips / highlights (include-gated). Null when requested but empty. ai_summary: type: object properties: text: type: string description: Markdown AI summary. nullable: true description: AI summary (include-gated). Null when requested but empty. ai_action_items: type: array items: type: object properties: status: type: string enum: - pending - completed timestamp_ms: type: integer description: Time in the recording the item was mentioned. text: type: string assignee: type: object nullable: true properties: id: type: string name: type: string user_id: type: string nullable: true nullable: true description: AI action items (include-gated). Null when requested but empty. ai_template_sections: type: array items: type: object nullable: true description: >- AI template sections, shape varies by template (include-gated). Null when requested but empty. calendar_event: type: object nullable: true properties: ical_uid: type: string description: Related calendar event (include-gated). hubspot: type: object properties: hubspot_company_ids: type: array items: type: string hubspot_deal_ids: type: array items: type: string nullable: true description: >- Related HubSpot company/deal ids (include-gated). Null when requested but empty. required: - source_type - grain_recording_id ZoomSourceMetadata: type: object description: >- Source provenance captured from Zoom at ingest time. Signed download/play URLs, share URLs, and passcodes are never included. properties: source_type: type: string enum: - zoom description: Discriminator identifying the upstream connector. zoom_meeting_uuid: type: string description: Zoom meeting instance UUID. zoom_meeting_id: type: integer description: Zoom numeric meeting id. nullable: true topic: type: string description: Meeting topic (empty string when Zoom omits it). nullable: true start_time: type: string format: date-time description: UTC time the meeting started. nullable: true host_id: type: string nullable: true description: Zoom host user id. host_email: type: string nullable: true description: >- Host email. Nullable whenever Zoom omits it — both list and per-meeting endpoints may return null depending on account scopes. account_id: type: string nullable: true description: Zoom account id. timezone: type: string nullable: true description: Meeting timezone. duration_minutes: type: number nullable: true description: Meeting duration in minutes (as reported by Zoom). total_size: type: number nullable: true description: Total size of all recording files in bytes. recording_count: type: number nullable: true description: Number of recording files for the meeting. meeting_type: type: number nullable: true description: Zoom's numeric meeting type. recording_files: type: array nullable: true items: type: object properties: id: type: string nullable: true recording_type: type: string nullable: true description: e.g. shared_screen_with_speaker_view, audio_only. file_type: type: string nullable: true file_extension: type: string nullable: true file_size: type: number nullable: true description: File size in bytes. recording_start: type: string nullable: true recording_end: type: string nullable: true status: type: string nullable: true description: >- Structural facts about each recording file. Download/play URLs are excluded. required: - source_type - zoom_meeting_uuid RecallSourceMetadata: type: object description: >- Source provenance captured from Recall at ingest time. Artifact availability is exposed as booleans — signed artifact download URLs are never included. properties: source_type: type: string enum: - recall description: Discriminator identifying the upstream connector. recall_recording_id: type: string description: Recall recording id. created_at: type: string nullable: true description: UTC time the recording object was created. started_at: type: string nullable: true description: UTC time recording started. completed_at: type: string nullable: true description: UTC time recording completed. expires_at: type: string nullable: true description: UTC time the recording expires upstream at Recall. status_code: type: string nullable: true description: >- Recall status: done, processing, failed, or paused. Only done recordings can be synced. meeting_title: type: string nullable: true description: Meeting title, when Recall's meeting metadata carries one. meeting_platform: type: string nullable: true description: Meeting platform (e.g. zoom, google_meet), when available. has_transcript: type: boolean description: Whether a transcript artifact exists. nullable: true has_audio: type: boolean description: Whether a separate audio artifact exists. nullable: true has_participant_events: type: boolean nullable: true description: Whether a participant-events artifact exists. bot_id: type: string nullable: true description: Id of the bot that captured the recording. recall_metadata: type: object nullable: true additionalProperties: true description: >- Arbitrary caller-supplied metadata attached to the bot/recording in Recall. required: - source_type - recall_recording_id GoogleDriveSourceMetadata: type: object description: >- Source provenance captured from Google Drive at ingest time. Short-lived signed URLs (e.g. thumbnailLink) are never included. properties: source_type: type: string enum: - google-drive description: Discriminator identifying the upstream connector. gdrive_file_id: type: string description: Drive file id. name: type: string description: File name. nullable: true mime_type: type: string nullable: true size_bytes: type: number nullable: true created_time: type: string nullable: true description: UTC time the file was created in Drive. modified_time: type: string nullable: true description: UTC time the file was last modified. web_view_link: type: string nullable: true description: Link to view the file in Drive (requires Drive access). owners: type: array nullable: true items: type: object properties: display_name: type: string nullable: true email_address: type: string nullable: true description: File owners. last_modifying_user: type: object nullable: true properties: display_name: type: string nullable: true email_address: type: string nullable: true description: User who last modified the file. parents: type: array nullable: true items: type: string description: Parent folder ids. shared: type: boolean nullable: true description: Whether the file is shared. file_extension: type: string nullable: true md5_checksum: type: string nullable: true video_media_metadata: type: object nullable: true properties: duration_millis: type: number nullable: true description: Video duration in milliseconds. width: type: number nullable: true height: type: number nullable: true description: Drive's video metadata, when Drive has processed the file. required: - source_type - gdrive_file_id DropboxSourceMetadata: type: object description: Source provenance captured from Dropbox at ingest time. properties: source_type: type: string enum: - dropbox description: Discriminator identifying the upstream connector. dropbox_id: type: string description: Dropbox file id (id:… form). name: type: string description: File name. nullable: true path_lower: type: string description: Lowercased path of the file. nullable: true path_display: type: string nullable: true description: Display-cased path. size_bytes: type: number nullable: true client_modified: type: string nullable: true description: Modification time reported by the client that uploaded the file. server_modified: type: string nullable: true description: Time the file was last modified on Dropbox. rev: type: string nullable: true description: Dropbox revision id. content_hash: type: string nullable: true description: Dropbox content hash. is_downloadable: type: boolean nullable: true media_info: type: object nullable: true properties: duration_ms: type: number nullable: true description: Media duration in milliseconds. width: type: number nullable: true height: type: number nullable: true description: >- Media dimensions/duration. Only populated at sync/lookup time — Dropbox's list endpoint stopped returning media info in 2019, so items in the list endpoint carry null here. required: - source_type - dropbox_id GongSourceMetadata: type: object description: >- Source provenance captured from Gong at ingest time. Signed media URLs are never included. AI content fields (topics, trackers, brief, key_points) require Gong Call Spotlight entitlement and are only captured at sync/lookup time. properties: source_type: type: string enum: - gong description: Discriminator identifying the upstream connector. gong_call_id: type: string description: Gong call id. title: type: string description: Call title (empty string when Gong omits it). nullable: true started: type: string nullable: true description: UTC time the call started. scheduled: type: string nullable: true description: UTC time the call was scheduled for. duration: type: number nullable: true description: Call duration in seconds. gong_url: type: string nullable: true description: URL to the call in Gong. meeting_url: type: string nullable: true description: URL of the underlying meeting. is_private: type: boolean nullable: true description: >- Whether the call is private in Gong. Private calls cannot be listed or synced. purpose: type: string nullable: true primary_user_id: type: string nullable: true description: Gong user id of the call owner. direction: type: string nullable: true description: Inbound, Outbound, Conference, or Unknown. system: type: string nullable: true description: Telephony/meeting system the call was held on. scope: type: string nullable: true description: Internal, External, or Unknown. language: type: string nullable: true description: ISO-639-2B language code Gong detected. workspace_id: type: string nullable: true description: Gong workspace id. call_media_type: type: string nullable: true description: 'Gong''s media indicator: Video or Audio.' parties: type: array nullable: true items: type: object properties: id: type: string nullable: true name: type: string nullable: true email: type: string nullable: true affiliation: type: string nullable: true description: Internal, External, or Unknown. speaker_id: type: string nullable: true user_id: type: string nullable: true description: Call participants. topics: type: array nullable: true items: type: object properties: name: type: string nullable: true duration: type: number nullable: true description: Seconds spent on the topic. description: AI topics (Call Spotlight). trackers: type: array nullable: true items: type: object properties: name: type: string nullable: true count: type: number nullable: true description: Tracker keyword hit counts (Call Spotlight). brief: type: string nullable: true description: AI call brief (Call Spotlight). key_points: type: array nullable: true items: type: string description: AI key points (Call Spotlight). required: - source_type - gong_call_id IconikSourceMetadata: type: object description: >- Source provenance captured from iconik at ingest time. Signed download URLs are never included. properties: source_type: type: string enum: - iconik description: Discriminator identifying the upstream connector. iconik_asset_id: type: string description: iconik asset id. title: type: string nullable: true description: Asset title. media_type: type: string nullable: true description: iconik media type of the asset (e.g. video, audio). date_created: type: string nullable: true description: UTC time the asset was created in iconik. date_modified: type: string nullable: true description: UTC time the asset was last modified in iconik. duration_ms: type: number nullable: true description: Asset duration in milliseconds, when iconik reports one. ingested_rendition: type: string enum: - proxy - original nullable: true description: >- Which rendition Cloudglue downloaded: the web proxy (preferred) or the ORIGINAL file. iconik_url: type: string nullable: true description: Deep link to the asset page in iconik. external_id: type: string nullable: true description: External reference id set on the asset in iconik. created_by_user: type: string nullable: true description: iconik user id that created the asset. iconik_metadata: type: object nullable: true additionalProperties: true description: >- Custom metadata-view field values from iconik (customer-defined schemas, e.g. a screening view's UGC Title / Keywords / Categories), captured verbatim keyed by field name. Indexed into metadata-collection search documents and filterable via source_metadata.iconik_metadata. paths. required: - source_type - iconik_asset_id securitySchemes: bearerAuth: type: http scheme: bearer ````