POST/v1/vectors/batch-insertREAD / WRITE

Batch insert

Insert many vectors into a collection in one request, with per-item idempotency.

Inserts every vector in batch in request order and returns their assigned ids in the same order. Prefer this over repeated Insert a record calls when writing more than a handful of vectors at once — one round trip instead of many.

Request body

batchnumber[][]required

The vectors to insert, in order. Each entry must match the collection's dimension.

collectionstringoptional

Target collection name. Optional at the HTTP level — pass it explicitly.

metadata(object | null)[]optional

Optional per-vector metadata, UTF-8 JSON strings on the wire (both SDKs accept and return plain objects). If present, must be the same length as batch — a null entry means "no metadata for this item," it does not shorten the array.

texts(string | null)[]optional

Optional per-vector text for hybrid term-frequency reranking. Same length requirement as metadata.

request_ids(string | null)[]optional

Optional per-item idempotency keys (32-hex-character strings). Same length requirement as metadata. A repeated key causes that item to be skipped — the id already assigned to it is returned instead of a new one.

metadata, texts, and request_ids are positional — index i in each array applies to batch[i]. Supplying one with a different length than batch is a validation error (code: "validation_error", 400); the contract does not specify the exact wording, so branch on code, not the message text.

Response fields

idsinteger[]required

The assigned (or deduplicated) id for each item, in the same order as batch.

Errors

Status	`code`	Meaning
`400`	`validation_error`, `dimension_mismatch`	Malformed request, or a per-item array's length doesn't match `batch`.
`401`	`unauthorized`	Missing or invalid API key.
`403`	`forbidden`	The key's scope doesn't include `read_write`.
`507`	`capacity_exceeded`	The project's record capacity is exhausted.

Related endpoints

Insert a record — single-vector insert
Vector search