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

# Run a bulk import

`POST /collections/{collection_id}/imports/{import_id}/runs`

## Request

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

Trigger a new run of a saved import. `mode` and `delete_missing` default to the definition's saved values. Only one run may be active per collection at a time, so triggering while any run in the collection is active returns a 409. Rerunning is also how a media import resumes after it stopped on exhausted credits or a usage limit: an `append` run skips files it already imported and retries the rest.

## Path parameters

- `collection_id` string, uuid, required
- `import_id` string, uuid, required

## Request body

- CreateMetadataImportRunRequest: All fields default to the values saved on the import definition.
  - `mode` 'append' | 'refresh'
  - `delete_missing` boolean
  - `max_files` integer: Override the definition's max_files for this run
  - `include_thumbnails` boolean: Override the definition's include_thumbnails for this run. Metadata imports only — setting it on a media import is a 400.
  - `enrich_metadata` boolean: Override the definition default for this run.

## Response `200`

The created 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).

## Other responses

- `400`: Invalid request — `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)
- `403`: Usage limit reached (monthly metadata-import files) — `code: usage_limit_reached`
- `404`: Collection or import not found
- `409`: A run of this import is already active, or another import in this collection has an active run
- `500`: The run could not be enqueued and was marked failed — trigger a new run to retry

## Changes

- **2026-10-30** `23d3f240819f`: 5 info
  - added the non-success response with the status `403`
  - 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 `409` status
  - …1 more
- **2026-08-18** `e401e330a58f`: 5 info
  - api tag `Bulk Imports` added
  - api tag `Metadata Imports` removed
  - added the non-success response with the status `400`
  - added the optional property `import_type` to the response with the `200` status
  - …1 more
- **2026-08-17** `b98a8a84c55f`: 3 info
  - added the new optional request property `enrich_metadata`
  - added the optional property `enrich_metadata` to the response with the `200` status
  - added the optional property `progress/files_enriched` to the response with the `200` status
- **2026-08-13** `96a727e8d42d`: 1 info
  - endpoint added

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