---
title: "Bulk Insert"
method: POST
path: "/helixdb/etl/bulk"
tags: ["HelixDB", "HelixDB ETL"]
---

# Bulk Insert

`POST /helixdb/etl/bulk`

## Request

- Base URL: `https://api.getmetacognition.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.getmetacognition.com/helixdb/etl/bulk`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/metacognition/apis/tex-api/docs/helixdb/etl/bulk/post.ts> (a function with typed inputs; its response is checked against the schema)

Bulk insert nodes/edges/vectors.

Optional `scope` ("<kind>:<value>") is the write stamp for every inserted
record; must be within the caller's visible scopes (403 otherwise).
Defaults to user:<user_id>.

## Request body

- BulkInsertRequest: Bulk insert request.
  - `nodes` NodeInsert[]: Nodes to insert
    - `label` string, required: Node type/label
    - `properties` object, required: Node properties
    - `id` string, nullable: Optional UUID
  - `edges` EdgeInsert[]: Edges to insert
    - `label` string, required: Edge type/label
    - `from` string, required: Source node UUID
    - `to` string, required: Target node UUID
    - `properties` object: Edge properties
  - `vectors` VectorInsert[]: Vectors to insert
    - `label` string, required: Vector label
    - `data` number[], nullable: Raw vector data
    - `text` string, nullable: Text to generate embedding from
    - `properties` object: Vector properties
    - `id` string, nullable: Optional UUID
  - `options` object: Insertion options
  - `scope` string, nullable: Optional explicit write scope "<kind>:<value>" (kinds: user/team/org/project). Must be within the caller's visible scopes; defaults to user:<user_id>.

## Response `200`

Successful Response

- BulkInsertResponse: Bulk insert response.
  - `success` boolean, required: Whether insertion succeeded
  - `nodes_inserted` integer: Number of nodes inserted
  - `edges_inserted` integer: Number of edges inserted
  - `vectors_inserted` integer: Number of vectors inserted
  - `errors` string[]: Error messages

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/metacognition/apis/tex-api.md) - [All operations](https://skmtc.dev/metacognition/apis/tex-api/llms.txt) - [OpenAPI document](https://skmtc.dev/metacognition/apis/tex-api/revisions/3bef47e50f2e?raw)