Batches

A batch represents a submitted job of assets. Collections of batches are returned from:

/customers/{customer}/queue/batches
/customers/{customer}/queue/active
/customers/{customer}/queue/recent
/customers/{customer}/iiif/<identifier>/queue/batches 🆕
/customers/{customer}/iiif/<identifier>/queue/active 🆕
/customers/{customer}/iiif/<identifier>/queue/recent 🆕

Typically you'd interact with a batch while it is being processed, or to update your internal systems with the status of assets on the platform. The data in a batch can be used to generate progress bars and other reporting information in your systems.

Old batches are kept on the platform for at least a year but are eventually archived.

{
    "@context": "https://dlcs.github.io/vocab/context/future.json",
    "@id": "https://api.dlcs.io/customers/2/queue/batches/875629",
    "@type": "vocab:Batch",
    "submitted": "2023-09-02T10:32:49.9404910Z",
    "count": 90,
    "completed": 90,
    "finished": "2023-09-02T10:45:17.4325100Z",
    "errors": 0,
    "superseded": false,
    "images": "https://api.dlcs.io/customers/2/queue/batches/875629/images",
    "completedImages": "https://api.dlcs.io/customers/2/queue/batches/875629/completedImages",
    "errorImages": "https://api.dlcs.io/customers/2/queue/batches/875629/errorImages",
    "test": "https://api.dlcs.io/customers/2/queue/batches/875629/test"
}

/customers/{customer}/queue/batches/{batch}

Method	Label	Expects	Returns	Status
GET	Retrieve a Batch	-	vocab:Batch	200 OK, 404 Not Found

submitted

The date and time the batch was created by the platform in response to receiving a collection of assets POSTed to the queue.

domain	range	readonly	writeonly
vocab:Batch	xsd:dateTime	True	False

count

The number of assets in the batch. The platform imposes a limit of 100 on the size of collections that can be submitted to a queue, therefore a batch cannot have a count greater than this.

domain	range	readonly	writeonly
vocab:Batch	xsd:integer	True	False

completed

The number of assets in the batch that have completed processing (whether or not they all succeeded).

domain	range	readonly	writeonly
vocab:Batch	xsd:integer	True	False

finished

The date and time the batch was finished processing. This will be absent if the batch is waiting to be processed or is still being processed. A finished batch may contain errors.

domain	range	readonly	writeonly
vocab:Batch	xsd:dateTime	True	False

superseded

We need to revisit how this works. See https://github.com/dlcs/protagonist/issues/491 (opens in a new tab)

Has this batch been superseded by another? An asset can only be associated with one active batch at a time. If no assets are associated with this batch, then it has been superseded by one or more later batches. The platform does not update this property automatically, you can force an update by POSTing to the test resource of a batch.

domain	range	readonly	writeonly
vocab:Batch	xsd:boolean	True	False

images

A link to a Collection of all the assets in the batch.

domain	range	readonly	writeonly
vocab:Space	🔗 hydra:Collection (of vocab:Image)	True	False

/customers/{customer}/queue/batches/{batchId}/images

Method	Label	Expects	Returns	Status
GET	Retrieves all assets in batch regardless of state	-	hydra:Collection	200 OK

The following information will likely change

An asset can only be associated with one batch. This means that if an asset is included in a subsequent batch, it will no longer be a member of this batch. If a batch has "lost" all its assets in this way, it is said to be superseded.

test

An HTTP POST to this resource will update the batch's superseded property

/customers/{customer}/queue/batches/{batchId}/test

Method	Label	Expects	Returns	Status
POST	Force an update of the batch.superseded property.	-	JSON object with single success property (boolean).	200 OK

touched 2025-09-23T12:04:54

Queue IIIF Manifests and Collections