Skip to content

Start an extraction backfill

POST
/admin/metadata-extraction/backfills

Queues a sweep that submits an extraction job for each eligible asset.

You need to be signed in with system.admin for the whole install; a permission held only for a team doesn’t count. Leave out the body or send {} for the default scope: active, non-deleted assets with a stored file hash and an image extension that extraction supports. That includes the supported camera raw formats, but not every image format.

When you send both asset-type and extension filters, an asset must match both. asset_type_ref and asset_type_refs merge into one deduplicated set of allowed types. Set include_non_image to true to drop the image-extension rule entirely; add file_extensions: ["pdf"] to target PDFs. A wider scope doesn’t mean a registered extractor can read every format it selects.

The coordinator reads eligible assets in UUID order, 500 at a time, and tries to queue a separate metadata.extract job for each. Its counters track those attempts, and completion means the sweep finished queueing, not that extraction finished. Eligibility is read as the sweep goes, not fixed when you submit. Each job reads the field settings when it applies values, not when you submit or when the job starts.

A 200 returns the run row as inserted, not a fresh progress read; use the list or get endpoint to follow it. Repeating the request creates another run, and runs can overlap. Creating the run and queueing the coordinator are separate writes: a queueing error can leave a run row behind, so a failed request doesn’t prove that no run was created.

Optional filters for a new backfill sweep. Without filters, the sweep selects active, non-deleted assets with a file hash and a supported image extension.

When both asset-type and extension filters are set, an asset must match both, and values within each filter are alternatives. The singleton and array asset-type fields merge into one deduplicated set. Eligibility is checked as the coordinator scans, not fixed when you submit.

object
asset_type_ref

One allowed asset-type reference, merged with asset_type_refs if that’s sent too. Null or leaving it out adds no type. References aren’t checked for existence when you submit.

integer format: int64
nullable
asset_type_refs

Allowed asset-type references. Duplicates are removed, and an empty or missing array adds no types. If neither type field supplies one, every asset type is eligible.

Array<integer>
file_extensions

Allowed file extensions, matched against the stored extension in lowercase. Each entry is trimmed, loses one leading dot and is lowercased; duplicates and empty results are dropped. If none are left, the filter is off. For PDFs, send ["pdf"] with include_non_image: true.

Array<string>
include_non_image

When true, drops the default image-extension rule while other filters still apply, so any format matching them is admitted, including formats no registered extractor handles. False or left out keeps the default supported-image set.

boolean

The run record as inserted, returned once the coordinator job is queued. Extraction runs in the background.

A recorded backfill sweep. Its counters track attempts to queue child extraction jobs, not whether those jobs finished or extracted values.

object
id
required

UUID of this backfill run. It is not the coordinator job ID.

string format: uuid
asset_type_ref

The singleton asset-type filter, if one was sent; left out otherwise. It doesn’t reflect asset_type_refs, extension filters or the non-image flag, so its absence doesn’t mean the run was unfiltered.

integer format: int64
nullable
total
required

Always zero in the current implementation, even after completion. It isn’t a count of eligible assets.

integer format: int64
processed
required

Queueing attempts counted by whichever coordinator attempt last saved progress. A retry restarts the count, and an asset can be counted more than once.

integer format: int64
succeeded
required

Queueing attempts that returned no error. It doesn’t count successful metadata extractions.

integer format: int64
failed
required

Queueing attempts that returned an error. Failures inside the child extraction jobs aren’t counted here.

integer format: int64
started_at
required

When the run row was inserted, before the coordinator was queued. It doesn’t show when a worker started processing.

string format: date-time
completed_at

When the coordinator finished its sweep; left out until then. Child extraction jobs can still be queued or running.

string format: date-time
nullable
cancelled_at

When the first accepted cancellation request for an unfinished run was recorded; left out until then. It doesn’t confirm that the worker has stopped.

string format: date-time
nullable
started_by_user_ref

Account reference of whoever started the run. Left out when unavailable, including after that account is hard-deleted.

integer format: int64
nullable

Authentication required, missing, or invalid

object
error
required

Human-readable error summary

string
Example
the request could not be completed
Example
{
"error": "authentication required: sign in and retry with a valid session or API token"
}

Authenticated but missing required capabilities

object
error
required

Human-readable error summary

string
Example
the request could not be completed