---
title: "Create multiple entities in bulk"
method: POST
path: "/entity-collections/{entity_collection_id}/entities/bulk"
tags: ["entityCollections > entities"]
---

# Create multiple entities in bulk

`POST /entity-collections/{entity_collection_id}/entities/bulk`

This method creates multiple entities within a specified entity collection in a single request. Each entity must be associated with at least one asset. This endpoint is useful for efficiently adding multiple entities, such as a roster of players or a group of characters.

## Path parameters

- `entity_collection_id` string, required

## Headers

- `x-api-key` string, required

## Request body

- object
  - `entities` EntityCollectionsEntityCollectionIdEntitiesBulkPostRequestBodyContentApplicationJsonSchemaEntitiesItems[], required
    - `name` string, required — The name of the entity.
    - `description` string — Optional description of the entity.
    - `metadata` EntityCollectionsEntityCollectionIdEntitiesBulkPostRequestBodyContentApplicationJsonSchemaEntitiesItemsMetadata — Optional metadata for the entity, provided as key-value pairs.
    - `asset_ids` string[], required — An array of asset IDs to associate with the entity. At least one asset ID is required.

## Response `201`

The entities have been successfully created.

- BulkCreateEntityResponse — An object that represents the response from a bulk entity creation operation. This response summarizes the outcome, including the number of entities successfully created and any errors encountered during the process.
  - `success_count` integer — The number of entities that were successfully created.
  - `failed_count` integer — The number of entities that failed to be created due to errors, such as missing assets.
  - `entities` BulkCreateEntityResponseEntitiesItems[] — An array of objects representing the entities that were successfully created. Each object includes the unique identifier, name, and current status.
    - `_id` string — The unique identifier of the entity.
    - `name` string — The name of the entity.
    - `status` string — The current status of the entity creation process. **Values**: - `processing`: The entity is being processed and is not yet ready for use in searches. - `ready``: The entity is fully processed and can be used in search queries.
  - `errors` BulkCreateEntityResponseErrorsItems[] — An array of error objects for entities that failed to be created. Each error object provides details about the failure, including the index of the entity in the original request, the entity's name, and the reason for the failure.
    - `entity_index` integer — The zero-based index of the entity in the original request array. This helps identify which specific entity failed to be created.
    - `entity_name` string — The name of the entity that failed to be created, as provided in the request.
    - `error_reason` string — A message explaining why the entity failed to be created.

## Other responses

- `400` — The request has failed.

---

[API](https://skmtc.net/twelvelabs/apis/twelvelabs-api.md) · [All operations](https://skmtc.net/twelvelabs/apis/twelvelabs-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/twelvelabs/twelvelabs-api/revisions/b6d766c2c340/schema)