Bulk Imports

Create a bulk import

Changed on Oct 30, 2026

Create a bulk import: a saved definition that lists a data connector's source files and brings each match into the collection. What a run ingests follows the collection's type (see import_type on the response). For a metadata collection it imports each file's source metadata as a collection file, with no media download or processing, and runs consume no credits. For any other collection type it imports the media itself: each matching file is ingested and processed exactly like a manual add, so it is billed per file and counts against the account's file usage limits. A media run that exhausts credits or a usage limit stops with a user-facing error and keeps everything it already imported — rerun in append mode to resume. By default the first run starts immediately (start: false saves the definition only). The response's latest_run is the triggered run; it is null when start is false or when another run is already active in the collection (the definition is saved, and can be run once that one finishes), and it is returned with status failed when the run could not be started (trigger a new run to retry). Runs page the connector — and, for media imports, add each file — with the account's default active API key, and fail with a clear error when the account has none.

post/collections/{collection_id}/imports

Request

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

Path parameters

collection_idstring uuid required

The ID of the metadata collection

Request body

namestring required

Display name for the import

connector_idstring uuid required

Data connector to list files from. Supported types: google-drive, dropbox, zoom, gong, recall, grain, iconik.

default_mode'append' | 'refresh'

Mode used when a run does not specify one. append imports new files and retries previously-failed ones; refresh re-imports everything the filters match.

delete_missingboolean

On refresh runs, remove files this import previously brought in that the source no longer returns. Only files imported by this import are ever removed — manually-added files and other imports are untouched.

rate_limitinteger

Upstream list requests per second. Defaults to a per-connector safe rate (e.g. gong 2, zoom 6, google-drive/dropbox 8) and is clamped to a per-connector ceiling (gong 3, iconik 12, zoom/grain/recall 10, google-drive/dropbox 20) sized to keep the whole account inside each provider's published rate budget.

startboolean

Trigger the first run immediately. false saves the definition only.

max_filesinteger

Stop each run after processing this many files from the listing. A capped run stops listing at the limit and never runs the delete-missing sweep — a truncated listing is incomplete by definition, so nothing is removed based on it. Media imports additionally cap every run at 10,000 files, whatever this is set to.

include_thumbnailsboolean

Copy connector poster images as default thumbnails for imported files, for sources that provide one (Grain, iconik, Google Drive, and Dropbox today). Off by default. Posters are copied in the background, so they do not slow the import itself and may appear shortly after a file is indexed. Metadata imports only — setting it on a media import is a 400, since imported media gets real thumbnails from the processing pipeline.

enrich_metadataboolean

Backfill source-metadata fields the connector's list endpoint omits, after each index batch settles: Gong parties + Call Spotlight content (batched - enriched docs are re-embedded so the content is searchable) and Dropbox media_info duration/dimensions (per-file). No-op for other connectors. Off by default: it spends upstream API budget and, for Gong, embedding work. Metadata imports only — setting it on a media import is a 400, since a media run ingests each file in full and has no metadata-only record to enrich.

Response

The created import, with latest_run reflecting the immediately-triggered first run when applicable

object'metadata_import'

idstring uuid

collection_idstring uuid

connector_idstring uuid

import_type'metadata' | 'media'

Inferred from the collection's type at creation and fixed for the import's lifetime. metadata (metadata collections): source metadata is indexed, no media is downloaded, runs are free. media (every other collection type): each matching file is ingested and processed exactly like a manual add, billed per file.

namestring

default_mode'append' | 'refresh'

Mode used when a run does not specify one

delete_missingboolean

Default delete-missing behavior for refresh runs

rate_limitinteger nullable

Upstream list requests per second; null means the per-connector safe default. Clamped to a per-connector ceiling at run time.

created_atnumber

Unix timestamp in milliseconds

max_filesinteger nullable

Per-run ceiling on files processed from the listing; null means unbounded

include_thumbnailsboolean

Whether runs copy connector poster images as default thumbnails for imported files (Grain and iconik today)