---
title: "Delete spans"
method: DELETE
path: "/v2/spans"
tags: ["Spans"]
---

# Delete spans

`DELETE /v2/spans`

Permanently deletes spans by their span IDs. This operation is irreversible.

Accepts between 1 and 5000 span IDs per request. Only spans within the
searched time window are considered; spans outside that window are not affected.

The optional `start_time` and `end_time` fields scope the search to a
specific time window. Each bound is independent: omitting `start_time`
defaults to two years ago; omitting `end_time` defaults to now. You may
provide either or both. Providing them when the approximate timestamp of
the target spans is known significantly reduces the amount of span data
the server must search.

A `200 OK` response always includes:
- `completed` — `true` if the operation finished and no retry is needed;
  `false` if the operation could not fully complete (retry the full request).
- `deleted_span_ids` — span IDs confirmed deleted in this request.
- `not_deleted_span_ids` — requested IDs not deleted: either not found within
  the supported time range, or not reached when `completed` is `false`.

The delete operation is idempotent — re-submitting already-deleted IDs is safe.

  <Note>This endpoint is in beta, read more [here](https://arize.com/docs/ax/rest-reference#api-version-stages).</Note>

## Request body

- DeleteSpansRequest
  - `project_id` string, required — The project ID containing the spans to delete
  - `span_ids` string[], required — List of span IDs to delete (maximum 5000)
  - `start_time` string, date-time — Scope the delete to spans starting at or after this timestamp (inclusive). ISO 8601 format (e.g., `2024-01-01T00:00:00Z`). Each bound is independent: omitting `start_time` defaults to two years ago; omitting `end_time` defaults to now. You may provide either or both.
  - `end_time` string, date-time — Scope the delete to spans starting before this timestamp (exclusive). ISO 8601 format (e.g., `2024-01-02T00:00:00Z`). Each bound is independent: omitting `start_time` defaults to two years ago; omitting `end_time` defaults to now. You may provide either or both.

## Response `200`

Spans deleted. The response body always includes:
- `completed`: whether all requested spans were fully processed. This endpoint is idempotent — retries are safe.
- `deleted_span_ids`: IDs of spans confirmed deleted.
- `not_deleted_span_ids`: IDs of spans not deleted — either not found, or not yet processed when `completed` is `false`.

- DeleteSpansResponse — Result of a DELETE /v2/spans request. `deleted_span_ids` lists every span ID confirmed deleted. `not_deleted_span_ids` lists every requested span ID that was **not** deleted. `completed` indicates whether the server fully processed all data for the request — **not** whether all spans were found and deleted. A span may appear in `not_deleted_span_ids` even when `completed` is `true` if it was not found in the system (never ingested or already deleted). When `completed` is `true`, every requested ID appears in exactly one of `deleted_span_ids` or `not_deleted_span_ids`. No retry is needed. When `completed` is `false`, the server could not fully process all data. Some IDs in `not_deleted_span_ids` may still be deletable — retry the original full request to resolve them. The delete is idempotent.
  - `completed` boolean, required — `true` when the server fully processed all data for the request — both lists are complete and no retry is needed. `false` when processing could not fully complete; retry the original request. Note: `completed` reflects whether all data was processed, not whether all requested spans existed.
  - `deleted_span_ids` string[], required — Span IDs confirmed deleted in this request.
  - `not_deleted_span_ids` string[], required — Requested span IDs that were not deleted. When `completed` is `true`, these were not found in the system (never ingested or already deleted). When `completed` is `false`, some IDs may not have been reached — retry to resolve them.

## Other responses

- `400` — Invalid request
- `401` — Authentication is required
- `403` — Insufficient permissions to access this resource
- `404` — Not found
- `422` — Unprocessable entity
- `429` — Rate limit exceeded
- `503` — Fatal mid-request error. Returned as `503 Service Unavailable` when the server encountered an unrecoverable error after partially processing the request. The caller should retry the original full request — the delete operation is idempotent.

---

[API](https://skmtc.net/arize-ai/apis/arize-rest-api.md) · [All operations](https://skmtc.net/arize-ai/apis/arize-rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/arize-ai/arize-rest-api/versions/2ce448f1de13/schema)