---
title: "Overwrite Chunk Metadata in Batches"
method: PUT
path: "/v3/collections/{collection_name}/chunks/metadata/batch"
tags: ["file-search"]
---

# Overwrite Chunk Metadata in Batches

`PUT /v3/collections/{collection_name}/chunks/metadata/batch`

Overwrite the `custom_metadata` object on up to 100 chunks in one request. Each item behaves like [Overwrite Chunk Metadata](/reference/v3/documents/chunk/metadata/replace). Returns 200 with one result per item, in order. Overwrite is destructive: omitted keys are removed and `{}` clears the target. Consider [copying the collection](/reference/collections/copy) first. Envelope, partial success, and `unknown` outcomes are covered in the [Batch Metadata & Relations](/guides/batch-writes) guide.

## Path parameters

- `collection_name` string, required

## Request body

- BatchChunkMetadataRequestV3 — Always an object with one key, `items`, even for a single item. A bare item object is rejected with 400.
  - `items` BatchChunkMetadataItemV3[], required — 1 to 100 items. The request body may not exceed 1 MiB of UTF-8 JSON.
    - `item_id` string, required — Non-empty string, unique within the request. Echoed on the matching result. Not an idempotency key.
    - `chunk_id` string, required — A chunk ID returned by the chunk list or a query result.
    - `metadata` object, required — Custom metadata for this item. Reserved keys are rejected the same way the single-item endpoint rejects them.

## Response `200`

Overwrite Chunk Metadata in Batches response.

- BatchChunkMetadataResponseV3
  - `results` BatchChunkMetadataResultV3[], required — One result per request item, in request order. Never empty for an accepted batch.
    - union — One entry per request item, in request order. Exactly one of `data` (status `succeeded`) or `error` (status `failed` or `unknown`) is present; a result never carries both or neither.
      - object — A succeeded item: carries `data` and never `error`.
        - `status` 'succeeded', required
        - `item_id` string, required — Echoed from the request item.
        - `http_status` integer, required — The status the matching single-item endpoint would have returned for this item.
        - `data` ChunkMetadataResponseV3, required
          - `chunk_id` string, required
          - `custom_metadata` object — The stored custom metadata object.
          - `metadata` object — Deprecated alias for `custom_metadata`; carries the same object.
          - `updated_at` string, nullable
          - `filterable` boolean — True when the metadata also reached the search index, so query filters can match it. False when the metadata is stored but filters may not match it yet.
      - object — A failed or unknown item: carries `error` and never `data`. `failed` is a definite failure; `unknown` (http_status 500, code `outcome_unknown`) means the write's outcome could not be confirmed, so read the target back before replaying.
        - `status` 'failed', required — Discriminator value: failed
        - `item_id` string, required — Echoed from the request item.
        - `http_status` integer, required — The status the matching single-item endpoint would have returned for this item.
        - `error` BatchItemErrorV3, required
          - `code` string, required — Stable error code. Item-level codes are the ones the matching single-item endpoint uses for the same failure, plus `outcome_unknown` and `relation_identity_ambiguous`.
          - `message` string, required
      - object — A failed or unknown item: carries `error` and never `data`. `failed` is a definite failure; `unknown` (http_status 500, code `outcome_unknown`) means the write's outcome could not be confirmed, so read the target back before replaying.
        - `status` 'unknown', required — Discriminator value: unknown
        - `item_id` string, required — Echoed from the request item.
        - `http_status` integer, required — The status the matching single-item endpoint would have returned for this item.
        - `error` BatchItemErrorV3, required
          - `code` string, required — Stable error code. Item-level codes are the ones the matching single-item endpoint uses for the same failure, plus `outcome_unknown` and `relation_identity_ambiguous`.
          - `message` string, required

## Other responses

- `400` — Rejected before any write: malformed envelope, item count outside 1 to 100, duplicate `item_id` or targets, or a structural field error.
- `401` — Missing or invalid authentication.
- `403` — API key cannot write to this collection.
- `404` — Collection not found. A missing item target is reported inside `results[]`.
- `413` — Request body larger than 1 MiB.

## Changes

- **2026-09-24** `61a9364ad042` — 3 warning, 12 info
  - removed the optional property `detail` from the response with the `401` status
  - removed the optional property `detail` from the response with the `403` status
  - removed the optional property `detail` from the response with the `404` status
  - added the optional property `status_code` to the response with the `401` status
  - …11 more
- **2026-09-17** `6ed36830de71` — 1 breaking, 1 info
  - added `subschema #2, subschema #3` to the `results/items/` response property `oneOf` list for the response status `200`
  - removed `subschema #2, subschema #3` from the `results/items/` response property `oneOf` list for the response status `200`
- **2026-09-15** `cce532822415` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/runcaptain/apis/api-reference/changes/v3/collections/:collection_name/chunks/metadata/batch/put.md)

---

[API](https://skmtc.dev/runcaptain/apis/api-reference.md) · [All operations](https://skmtc.dev/runcaptain/apis/api-reference/llms.txt) · [OpenAPI document](https://skmtc.dev/runcaptain/apis/api-reference/revisions/ac61e472bb7d?raw)