Bulk Delete Entities

Learn how to use the Bulk Delete Entities task to remove multiple profiles from a tenant by using filters or entity URIs.

The Bulk Delete Entities task uses the Delete entities by entity type task to remove entities based on a specified filter or list of entity URIs.

The Bulk Delete Entities task executes a search request to identify the target entities and deletes them by iterating over the results. This task supports distributed mode, which allows it to run in parallel across multiple API nodes for greater scalability. This approach is recommended for large-scale or tenant-wide deletions.

Before you run the Bulk Delete Entities task, run the Cassandra ES Consistency task to ensure that the Elasticsearch storage is in a consistent state with the main data storage. For more information, see Delete Entities Task and Cassandra ES Consistency Task.

This operation on the Developer portal is here.

HTTP method and endpoint

Use the following HTTP method and endpoint path to submit the request to delete entities that match the specified filter or entity URI list.

POST {TenantURL}/entities/_delete

Query parameters

The following table describes the query parameters and their values. A query parameter is a key-value pair added to the end of a URL to modify or refine a request.


Parameter	Type	Required	Description	Accepted values / Default
`mode`	String	No	Specifies how entities are removed.	`soft` or `hard`. `soft` marks the entity as deleted but keeps all data in storage. `hard` retains entity data such as entity ID, version, and date fields, and removes other data such as crosswalks and attributes from storage. Default: not specified in source. Note: Entities that only have the soft parameter mode enabled are also removed.
`sendMail`	Boolean	No	Specifies whether an email is sent after the task is completed.	If not specified, an email is not sent.
`distributed`	Boolean	No	Specifies whether the task is distributed or not. For more information, see Distributed mode.	`true` or `false`. Default: `false`.
`taskPartsCount`	Integer	No	Specifies the maximum number of sub-tasks for distributed execution. The platform determines the optimal number based on performance limits. Each sub-task processes a separate subset of objects and can run in parallel on different API nodes.	Applicable only when `distributed=true`. If not specified and `distributed` is true, default: `4`. Otherwise, ignored.

Request headers

The following request headers must be included.


Header	Value	Required
`Authorization`	Bearer `<accessToken>`	Yes

For more information, see Authentication API.

Request body

The following table describes the request body parameters, including accepted values and defaults.


Parameter	Type	Required	Description	Accepted values / Default
objects	Object	Yes	Container for the delete request parameters.	JSON object.
filter	String	No	Search filter that identifies the entities to delete.	Search filter expression.
list	Array	No	List of entity URIs to delete. If you specify entity URIs, the task processes only those entities.	JSON array of entity URIs.
excludeList	Array	No	List of entity URIs to exclude from deletion when a filter is used.	JSON array of entity URIs.
options	Object	No	Additional search options for the request.	Search options object.
activeness	String	No	Activeness filter for the search request.	Activeness value.

Example request

Use the following example to see how a complete request is structured with headers and a JSON body.

POST {TenantURL}/entities/_delete
Headers: Authorization: Bearer {your-access-token}
{
  "objects": {
    "filter": "startsWith(attributes.LastName, 'Ind')",
    "excludeList": [ "entities/i2", "entities/i3" ]
  }
}

Response body

The following table describes the fields returned in the response body.


Parameter	Type	Description
`numberOfProcessedObjects`	Number	Number of deleted entities since the task started.
`objectsFailedToDeleteCount`	Number	Number of objects that were not deleted.
`objectsFailedToDelete`	Array	Entity IDs that were not deleted. Only 100 entity IDs that were not deleted are displayed.
`name`	String	Name of the manual task in the following format: `<Hard/Soft> Delete Entities By Type: <entity type URI>`.
`started`	Time	Time when the task started.
`throughput`	Number	Current speed of the task, which is the number of entities deleted per second.
`tenant`	String	Name of the tenant.
`current`	Time	Current system time.

Example response

The following example shows a response with the launched task details.

{
  "id": "f3d47316-c249-4e60-9a8a-8e97cc9ca0e3",
  ...
  "parameters": {
    "tenantId": "jondoe",
    "entityType": "HCP",
    "mode": "hard"
  },
  "currentState": {
    "objectsFailedToDelete": [
      "1AlLNjPS",
      "8C06vMB"
    ],
    "entityType": "configuration/entityTypes/HCP",
    "lastExecutionEC2Instances": "i-i-{instance-id}",
    "objectsFailedToDeleteCount": 2,
    "numberOfFailedToPublishEvents": 0,
    "lastHourThroughput": 0.0,
    "numberOfProcessedObjects": 126,
    "status": "Completed"
  },
  "throughput": 9.692307,
  "duration": "13s"
}

Unify and manage your data