Run Bulk Import

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.

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

Run a bulk import

cURL

curl --request POST \
  --url https://api.cloudglue.dev/v1/collections/{collection_id}/imports/{import_id}/runs \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "delete_missing": true,
  "max_files": 500000,
  "include_thumbnails": true,
  "enrich_metadata": true
}
'

200

{
  "object": "metadata_import_run",
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "import_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "import_type": "metadata",
  "mode": "append",
  "delete_missing": true,
  "status": "pending",
  "progress": {
    "pages_listed": 123,
    "files_listed": 123,
    "files_created": 123,
    "files_updated": 123,
    "files_skipped": 123,
    "files_failed": 123,
    "files_queued": 123,
    "files_indexed": 123,
    "files_imported": 123,
    "files_removed": 123,
    "files_enriched": 123
  },
  "error": "<string>",
  "started_at": 123,
  "completed_at": 123,
  "created_at": 123,
  "max_files": 123,
  "include_thumbnails": true,
  "enrich_metadata": true
}

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

collection_id · string<uuid> · required

The ID of the metadata collection

import_id · string<uuid> · required

The ID of the metadata import

Body

application/json

All fields default to the values saved on the import definition.

mode · enum<string>

Available options: append, refresh

delete_missing · boolean

max_files · integer

Override the definition's max_files for this run

Required range: 1 <= x <= 1000000

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

application/json

The created run

One execution of a metadata import.

object · enum<string>

Available options: metadata_import_run

id · string<uuid>

import_id · string<uuid>

import_type · enum<string>

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

Available options: metadata, media

mode · enum<string>

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.

Available options: append, refresh

delete_missing · boolean

Whether this run sweeps files this import previously brought in that the source no longer returns (refresh runs only)

status · enum<string>

Available options: pending, processing, completed, failed, cancelled

progress · object

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.

Show child attributes

error · string | null

User-facing failure reason when status is failed

started_at · number | null

Unix timestamp in milliseconds

completed_at · number | null

Unix timestamp in milliseconds

created_at · number

Unix timestamp in milliseconds

max_files · integer | null

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