Skip to content

List pending extraction failures

GET
/admin/metadata-extraction/failures

Returns the recorded extraction failures that haven’t been dismissed.

You need to be signed in with system.metadata_extraction.read or system.admin for the whole install; a permission held only for a team doesn’t count. The queue covers the whole install, with no filtering by asset owner or visibility.

Filter with error_kind and format, which match exact, case-sensitive strings. Leave a filter out to include every value; an empty string is still an exact filter. Results are newest first by occurred_at, and rows with equal timestamps have no fixed order.

items holds the requested page and total counts every pending row matching the same filters, ignoring paging. The page and the count are separate database reads, so concurrent inserts, dismissals or asset deletions can make them disagree, and offset paging can skip or repeat rows while the queue changes.

An empty page returns items: [], and total can still be positive when the offset is past the last match. Database failures use the server’s error response. The queue holds the extraction failures that were recorded, not every job that went wrong.

error_kind
string

Exact failure kind to filter by, such as unsupported_format, malformed_file, library_panic or validation. Storage also allows no_metadata. Leave it out for every kind; an unknown string normally matches no rows.

format
string

Exact source MIME type to filter by, such as image/jpeg. Matching is case-sensitive; leave it out for every format.

limit
integer
default: 50 >= 1 <= 200

Requested page size, from 1 to 200 rows. Defaults to 50.

offset
integer
0

Number of matching rows to skip, 0 by default. Use a non-negative value. Pages aren’t a stable snapshot of a changing queue.

The requested page of pending failures and a separately read count under the same filters.

A page of pending extraction failures and a count under the same filters.

object
items
required

The requested failure rows, newest first by occurred_at. Empty when the page has none.

Array<object>

One recorded extraction failure for an asset. An asset can have several rows, for example from different extractors or attempts. Dismissing a row hides it from the pending queue without erasing its details.

object
id
required

UUID of this failure row.

string format: uuid
asset_id
required

UUID of the asset the failure belongs to.

string format: uuid
format
required

Source MIME type recorded for this failure.

string
error_kind
required

How the failure was classified. Current writers use unsupported_format, malformed_file, library_panic and validation; storage also allows no_metadata. It’s a plain string, not a schema enum.

string
message
required

Diagnostic message recorded by extraction or validation. It can include details taken from the source metadata.

string
field_key

Canonical extraction key of the rejected field, such as camera_model. Left out when no field key was recorded.

string
raw_value

The rejected extracted value, decoded from stored JSON, so its shape varies. Left out when the decoded value is null or no usable value exists; whole-file failures normally leave it out.

occurred_at
required

When the failure row was inserted.

string format: date-time
dismissed_at

When the row was dismissed, if it has been. Pending-list responses leave it out, because they only return undismissed rows.

string format: date-time
nullable
total
required

Pending rows matching the filters, ignoring limit and offset. It’s read separately from items, so concurrent changes can make the two disagree.

integer format: int64

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