# Batches (/en/docs/api/native/media/batches)



[Guide →](/en/docs/developers/services/media/quickstart)

[Base URL and authentication](/en/docs/api/native/media)

## Create batch [#create-batch]

`POST /media/v1/libraries/{library_id}/batches`

| Parameter | Location | Type | Description |
| --- | --- | --- | --- |
| library_id | path | string | Library ID |

### Request body [#request-body]

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| action | "tag" / "untag" | yes | Batch action |
| tags | string[] | yes | Asset tags. Uploads accept a comma-separated string (items trimmed, empty items dropped), an array, or repeated tags fields; PATCH accepts an array only and replaces the whole list |

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| action | "set_context" | yes | Batch action |
| context | object | yes | Custom text key/value pairs; PATCH replaces the whole map, {} clears it |

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| action | "move" | yes | Batch action |
| asset_folder | string | yes | Organizational folder; does not change public_id. Listing by it matches that level only, not subfolders; an empty string is the root |

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| action | "delete" | yes | Batch action |

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| selector | BatchSelector | yes | Select by IDs or expression |

Returns: `Job`.

### Response [#response]

#### HTTP 200 [#http-200]

Successful response.

**application/json**

| Name | Type | Description |
| --- | --- | --- |
| id | string | Generated batch identifier: job_ followed by 32 lowercase hexadecimal characters. |
| library_id | string | Identifier of the library in which the batch operates. |
| action | string | Batch operation: tag adds labels, untag removes labels, set_context replaces custom metadata, move changes asset_folder, and delete removes selected assets. |
| status | string | Job status: queued awaits execution; running is processing items; completed means all items succeeded; completed_with_errors means some succeeded and some failed; failed means all selected items failed. An empty job completes successfully. |
| total | number | Number of distinct assets selected when the job was created. |
| done | number | Number of items successfully processed; failed items are counted separately. |
| failed | number | Number of items that could not be processed successfully. |
| failures | array<object> | Always present, including an empty array before any item failure or when all items succeed. At most 20 item failures are returned. |
| failures[].asset_id | string | Identifier supplied for the failed item; it may identify a missing asset. |
| failures[].code | string | Domain error code explaining the individual item failure. |
| created_at | string | Time the batch job was created, in UTC. |
| finished_at | string | null | Time the job reached a terminal status, or null while queued or running. |

```bash
curl -X POST "https://api.deepraxis.ai/media/v1/libraries/${LIBRARY_ID}/batches" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"action":"tag","tags":["sample"],"selector":{"ids":["85b7ef616a8b4719a41777a036ebc1d2","00000000000000000000000000000000"]}}'
```

HTTP 200

```json
{
  "id": "job_b562f087623c4756b43813e3dce670ba",
  "library_id": "lib_d3881a2f54a34cd79121b9d659e8378c",
  "action": "tag",
  "status": "queued",
  "total": 2,
  "done": 0,
  "failed": 0,
  "created_at": "2026-10-11T15:50:24.942Z",
  "failures": [],
  "finished_at": null
}
```

## Get batch [#get-batch]

`GET /media/v1/libraries/{library_id}/batches/{job_id}`

| Parameter | Location | Type | Description |
| --- | --- | --- | --- |
| library_id | path | string | Library ID |
| job_id | path | string | Job ID |

Returns: `Job`.

### Response [#response-1]

#### HTTP 200 [#http-200-1]

Successful response.

**application/json**

| Name | Type | Description |
| --- | --- | --- |
| id | string | Generated batch identifier: job_ followed by 32 lowercase hexadecimal characters. |
| library_id | string | Identifier of the library in which the batch operates. |
| action | string | Batch operation: tag adds labels, untag removes labels, set_context replaces custom metadata, move changes asset_folder, and delete removes selected assets. |
| status | string | Job status: queued awaits execution; running is processing items; completed means all items succeeded; completed_with_errors means some succeeded and some failed; failed means all selected items failed. An empty job completes successfully. |
| total | number | Number of distinct assets selected when the job was created. |
| done | number | Number of items successfully processed; failed items are counted separately. |
| failed | number | Number of items that could not be processed successfully. |
| failures | array<object> | Always present, including an empty array before any item failure or when all items succeed. At most 20 item failures are returned. |
| failures[].asset_id | string | Identifier supplied for the failed item; it may identify a missing asset. |
| failures[].code | string | Domain error code explaining the individual item failure. |
| created_at | string | Time the batch job was created, in UTC. |
| finished_at | string | null | Time the job reached a terminal status, or null while queued or running. |

```bash
curl -X GET "https://api.deepraxis.ai/media/v1/libraries/${LIBRARY_ID}/batches/job_b562f087623c4756b43813e3dce670ba" \
  -H "Authorization: Bearer $PRAXIS_API_KEY"
```

HTTP 200

```json
{
  "id": "job_b562f087623c4756b43813e3dce670ba",
  "library_id": "lib_d3881a2f54a34cd79121b9d659e8378c",
  "action": "tag",
  "status": "completed_with_errors",
  "total": 2,
  "done": 1,
  "failed": 1,
  "created_at": "2026-10-11T15:50:24.942Z",
  "failures": [
    {
      "asset_id": "00000000000000000000000000000000",
      "code": "ASSET_NOT_FOUND"
    }
  ],
  "finished_at": "2026-10-11T15:50:27.555Z"
}
```

## Batch assets alias [#batch-assets-alias]

`POST /media/v1/libraries/{library_id}/assets:batch`

| Parameter | Location | Type | Description |
| --- | --- | --- | --- |
| library_id | path | string | Library ID |

### Request body [#request-body-1]

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| action | "tag" / "untag" | yes | Batch action |
| tags | string[] | yes | Asset tags. Uploads accept a comma-separated string (items trimmed, empty items dropped), an array, or repeated tags fields; PATCH accepts an array only and replaces the whole list |

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| action | "set_context" | yes | Batch action |
| context | object | yes | Custom text key/value pairs; PATCH replaces the whole map, {} clears it |

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| action | "move" | yes | Batch action |
| asset_folder | string | yes | Organizational folder; does not change public_id. Listing by it matches that level only, not subfolders; an empty string is the root |

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| action | "delete" | yes | Batch action |

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| selector | BatchSelector | yes | Select by IDs or expression |

Returns: `Job`.

### Response [#response-2]

#### HTTP 200 [#http-200-2]

Successful response.

**application/json**

| Name | Type | Description |
| --- | --- | --- |
| id | string | Generated batch identifier: job_ followed by 32 lowercase hexadecimal characters. |
| library_id | string | Identifier of the library in which the batch operates. |
| action | string | Batch operation: tag adds labels, untag removes labels, set_context replaces custom metadata, move changes asset_folder, and delete removes selected assets. |
| status | string | Job status: queued awaits execution; running is processing items; completed means all items succeeded; completed_with_errors means some succeeded and some failed; failed means all selected items failed. An empty job completes successfully. |
| total | number | Number of distinct assets selected when the job was created. |
| done | number | Number of items successfully processed; failed items are counted separately. |
| failed | number | Number of items that could not be processed successfully. |
| failures | array<object> | Always present, including an empty array before any item failure or when all items succeed. At most 20 item failures are returned. |
| failures[].asset_id | string | Identifier supplied for the failed item; it may identify a missing asset. |
| failures[].code | string | Domain error code explaining the individual item failure. |
| created_at | string | Time the batch job was created, in UTC. |
| finished_at | string | null | Time the job reached a terminal status, or null while queued or running. |

```bash
curl -X POST "https://api.deepraxis.ai/media/v1/libraries/${LIBRARY_ID}/assets:batch" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"action":"tag","tags":["sample"],"selector":{"ids":["85b7ef616a8b4719a41777a036ebc1d2"]}}'
```

HTTP 200

```json
{
  "id": "job_3c2fe728de054c7396058c7438b289d2",
  "library_id": "lib_d3881a2f54a34cd79121b9d659e8378c",
  "action": "tag",
  "status": "queued",
  "total": 1,
  "done": 0,
  "failed": 0,
  "created_at": "2026-10-11T15:50:29.266Z",
  "failures": [],
  "finished_at": null
}
```

## Get job alias [#get-job-alias]

`GET /media/v1/libraries/{library_id}/jobs/{job_id}`

| Parameter | Location | Type | Description |
| --- | --- | --- | --- |
| library_id | path | string | Library ID |
| job_id | path | string | Job ID |

Returns: `Job`.

### Response [#response-3]

#### HTTP 200 [#http-200-3]

Successful response.

**application/json**

| Name | Type | Description |
| --- | --- | --- |
| id | string | Generated batch identifier: job_ followed by 32 lowercase hexadecimal characters. |
| library_id | string | Identifier of the library in which the batch operates. |
| action | string | Batch operation: tag adds labels, untag removes labels, set_context replaces custom metadata, move changes asset_folder, and delete removes selected assets. |
| status | string | Job status: queued awaits execution; running is processing items; completed means all items succeeded; completed_with_errors means some succeeded and some failed; failed means all selected items failed. An empty job completes successfully. |
| total | number | Number of distinct assets selected when the job was created. |
| done | number | Number of items successfully processed; failed items are counted separately. |
| failed | number | Number of items that could not be processed successfully. |
| failures | array<object> | Always present, including an empty array before any item failure or when all items succeed. At most 20 item failures are returned. |
| failures[].asset_id | string | Identifier supplied for the failed item; it may identify a missing asset. |
| failures[].code | string | Domain error code explaining the individual item failure. |
| created_at | string | Time the batch job was created, in UTC. |
| finished_at | string | null | Time the job reached a terminal status, or null while queued or running. |

```bash
curl -X GET "https://api.deepraxis.ai/media/v1/libraries/${LIBRARY_ID}/jobs/job_3c2fe728de054c7396058c7438b289d2" \
  -H "Authorization: Bearer $PRAXIS_API_KEY"
```

HTTP 200

```json
{
  "id": "job_3c2fe728de054c7396058c7438b289d2",
  "library_id": "lib_d3881a2f54a34cd79121b9d659e8378c",
  "action": "tag",
  "status": "completed",
  "total": 1,
  "done": 1,
  "failed": 0,
  "created_at": "2026-10-11T15:50:29.266Z",
  "failures": [],
  "finished_at": "2026-10-11T15:50:29.494Z"
}
```

## Job [#job]

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| id | JobId | yes | Resource ID |
| library_id | LibraryId | yes | Library ID |
| action | tag / untag / set_context / move / delete | yes | Batch action |
| status | "queued" / "running" / "completed" / "completed_with_errors" / "failed" | yes | Resource status |
| total | number | yes | Total assets in this job |
| done | number | yes | Completed count; completion flag for chunk responses |
| failed | number | yes | Failure count |
| failures | object[] | yes | — |
| created_at | IsoTimestamp | yes | Creation time |
| finished_at | IsoTimestamp / null | yes | Completion time; null while unfinished |

## BatchSelector [#batchselector]

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| ids | AssetId[] | yes | Asset IDs |

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| expression | string | yes | Structured query expression; an empty expression returns every asset |
| exclusions | AssetId[] | no | Asset IDs excluded from selection |

## BatchAction [#batchaction]

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| action | "tag" / "untag" | yes | Batch action |
| tags | string[] | yes | Asset tags. Uploads accept a comma-separated string (items trimmed, empty items dropped), an array, or repeated tags fields; PATCH accepts an array only and replaces the whole list |

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| action | "set_context" | yes | Batch action |
| context | object | yes | Custom text key/value pairs; PATCH replaces the whole map, {} clears it |

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| action | "move" | yes | Batch action |
| asset_folder | string | yes | Organizational folder; does not change public_id. Listing by it matches that level only, not subfolders; an empty string is the root |

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| action | "delete" | yes | Batch action |