Skip to content

Get an extraction backfill

GET
/admin/metadata-extraction/backfills/{id}

Returns the recorded progress of one metadata-extraction backfill.

You need to be signed in with system.admin for the whole install; a permission held only for a team doesn’t count. With it you can read any run, whoever started it. A missing run returns 404.

processed, succeeded and failed count the coordinator’s attempts to queue jobs, and total stays zero. Progress is saved between batches on a best-effort basis, and a retried coordinator restarts its counters and its scan, so this isn’t a running total of successful extractions.

completed_at means the coordinator finished its sweep. cancelled_at records a cancellation request, which the worker checks between batches. Both can be set if completion and cancellation race. Missing terminal timestamps don’t prove the coordinator is still running. The response doesn’t show the full saved filter set or the coordinator job’s status or error.

id
required
string format: uuid

UUID of the backfill run to read.

The run record as stored when read, with its last saved queueing counters.

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

Resource not found

object
error
required

Human-readable error summary

string
Example
the request could not be completed