Skip to content

List recent extraction backfills

GET
/admin/metadata-extraction/backfills

Returns the most recently created metadata-extraction backfill runs.

You need to be signed in with system.admin for the whole install; a permission held only for a team doesn’t count. system.metadata_extraction.read, which opens the failure queue, doesn’t open this list. Runs started by any administrator are included, completed and cancelled ones too.

Results are newest first by started_at, and ties have no fixed order. limit defaults to 20, up to 50. There’s no offset, cursor or total count, so you can’t page back to older runs. With no runs you get items: [].

The counters track attempts to queue extraction jobs, not whether those jobs finished or extracted any metadata. Reads go straight to the database, and a running sweep saves its progress between batches on a best-effort basis.

limit
integer
default: 20 >= 1 <= 50

Maximum number of recent runs to return, from 1 to 50. Defaults to 20.

Recent run records, newest first. An empty list is returned as items: [].

A bounded list of recent backfill runs, with no pagination token or total count.

object
items
required

Run records, newest first by started_at; ties have no fixed order. Empty when no runs exist.

Array<object>

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