---
title: "Create a bulk import"
method: POST
path: "/collections/{collection_id}/imports"
tags: ["Bulk Imports"]
---

# Create a bulk import

`POST /collections/{collection_id}/imports`

## Request

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

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.

## Path parameters

- `collection_id` string, uuid, required

## Request body

- CreateMetadataImportRequest
  - `name` string, required: Display name for the import
  - `connector_id` string, uuid, required: Data connector to list files from. Supported types: google-drive, dropbox, zoom, gong, recall, grain, iconik.
  - `filters` MetadataImportFilterSet[]: Listing passes; empty (the default) means one unfiltered pass
    - `from` string, date: Only include source files from on/after this date (YYYY-MM-DD, UTC)
    - `to` string, date: Only include source files from on/before this date (YYYY-MM-DD, UTC)
    - `folder_id` string: Restrict listing to a folder's direct children (Google Drive only). Omit to list the entire corpus.
    - `path` string: Restrict listing to a folder path (Dropbox only). Dropbox listing is non-recursive: an import ingests only the direct children of this path (or of the root when omitted — typically all folders, i.e. nothing). Use one filter set per folder to cover a tree.
    - `title_search` string: Only include files whose title matches this search
    - `team` string: Restrict to a team (Grain only)
    - `meeting_type` string: Restrict to a meeting type (Grain only)
    - `recursive` 'true' | 'false': Dropbox only: 'true' imports the whole subtree under `path` (or the whole account when no `path` is given) instead of direct children.
  - `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_missing` boolean: 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_limit` integer: 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.
  - `start` boolean: Trigger the first run immediately. false saves the definition only.
  - `max_files` integer: 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_thumbnails` boolean: 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_metadata` boolean: 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 `200`

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

- MetadataImport: A saved bulk import: which connector to list, how to filter it, and how runs behave. What a run ingests depends on the collection — see import_type. Definitions are immutable — delete and recreate to change one.
  - `object` 'metadata_import'
  - `id` string, uuid
  - `collection_id` string, uuid
  - `connector_id` string, 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.
  - `name` string
  - `filters` MetadataImportFilterSet[]: Listing passes; an empty array means one unfiltered pass. Overlapping passes are deduplicated on import.
    - `from` string, date: Only include source files from on/after this date (YYYY-MM-DD, UTC)
    - `to` string, date: Only include source files from on/before this date (YYYY-MM-DD, UTC)
    - `folder_id` string: Restrict listing to a folder's direct children (Google Drive only). Omit to list the entire corpus.
    - `path` string: Restrict listing to a folder path (Dropbox only). Dropbox listing is non-recursive: an import ingests only the direct children of this path (or of the root when omitted — typically all folders, i.e. nothing). Use one filter set per folder to cover a tree.
    - `title_search` string: Only include files whose title matches this search
    - `team` string: Restrict to a team (Grain only)
    - `meeting_type` string: Restrict to a meeting type (Grain only)
    - `recursive` 'true' | 'false': Dropbox only: 'true' imports the whole subtree under `path` (or the whole account when no `path` is given) instead of direct children.
  - `default_mode` 'append' | 'refresh': Mode used when a run does not specify one
  - `delete_missing` boolean: Default delete-missing behavior for refresh runs
  - `rate_limit` integer, nullable: Upstream list requests per second; null means the per-connector safe default. Clamped to a per-connector ceiling at run time.
  - `created_at` number: Unix timestamp in milliseconds
  - `latest_run` MetadataImportRun: One execution of a metadata import.
    - `object` 'metadata_import_run'
    - `id` string, uuid
    - `import_id` string, uuid
    - `import_type` 'metadata' | 'media': What this run ingests, inherited from the import definition: metadata indexes source metadata only (free); media ingests and processes the actual files (billed per file).
    - `mode` 'append' | 'refresh': append imports new files and retries previously-failed ones; refresh re-imports everything the filters match. For media imports, refresh re-syncs the source metadata of files it already imported — media bytes are never re-downloaded.
    - `delete_missing` boolean: Whether this run sweeps files this import previously brought in that the source no longer returns (refresh runs only)
    - `status` 'pending' | 'processing' | 'completed' | 'failed' | 'cancelled'
    - `progress` MetadataImportRunProgress: Best-effort progress counters for display. Run completion is decided from the actual per-file indexing state, never from these counters, so they can drift slightly under retries without affecting correctness.
      - `pages_listed` integer: Connector list pages fetched
      - `files_listed` integer: Source files seen across all filter sets
      - `files_created` integer: New Cloudglue files created
      - `files_updated` integer: Existing files re-imported (refresh mode)
      - `files_skipped` integer: Already-imported files left untouched (append mode)
      - `files_failed` integer: Files whose metadata indexing failed
      - `files_queued` integer: Files handed to indexing — the denominator for progress (indexed + failed settle against it)
      - `files_indexed` integer: Files whose metadata finished indexing (metadata imports)
      - `files_imported` integer: Files whose media was ingested and added to the collection (media imports)
      - `files_removed` integer: Files removed by the delete-missing sweep
      - `files_enriched` integer: Files whose source_metadata an enrichment batch backfilled (enrich_metadata runs only).
    - `error` string, nullable: User-facing failure reason when status is failed
    - `started_at` number, nullable: Unix timestamp in milliseconds
    - `completed_at` number, nullable: Unix timestamp in milliseconds
    - `created_at` number: Unix timestamp in milliseconds
    - `max_files` integer, nullable: The cap this run executed with; null means unbounded
    - `include_thumbnails` boolean: Whether this run copied poster thumbnails
    - `enrich_metadata` boolean: Whether this run backfills omitted source-metadata fields (see the import-level property).
  - `max_files` integer, nullable: Per-run ceiling on files processed from the listing; null means unbounded
  - `include_thumbnails` boolean: Whether runs copy connector poster images as default thumbnails for imported files (Grain and iconik today)
  - `enrich_metadata` boolean: 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.

## Other responses

- `400`: Invalid request — the connector does not exist, the connector type does not support imports, a filter key is not supported by the connector type, or `include_thumbnails` or `enrich_metadata` was set on a media import (imported media gets real thumbnails from the processing pipeline, and a media run has no metadata-only record to enrich)
- `404`: Collection 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-08-18** `e401e330a58f`: 5 info
  - api tag `Bulk Imports` added
  - api tag `Metadata Imports` removed
  - added the optional property `import_type` to the response with the `200` status
  - added the optional property `latest_run/allOf[#/components/schemas/MetadataImportRun]/import_type` to the response with the `200` status
  - …1 more
- **2026-08-17** `b98a8a84c55f`: 6 info
  - added the new optional request property `enrich_metadata`
  - added the new optional request property `filters/items/recursive`
  - added the optional property `enrich_metadata` to the response with the `200` status
  - added the optional property `filters/items/recursive` to the response with the `200` status
  - …2 more
- **2026-08-13** `96a727e8d42d`: 1 info
  - endpoint added

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