> ## Documentation Index
> Fetch the complete documentation index at: https://arize-ax.mintlify.site/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Delete 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
supported lookback window (2 years) are considered; older spans are not affected.
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 lookback window, or not reached when `completed` is `false`.
The delete operation is idempotent — re-submitting already-deleted IDs is safe.
This endpoint is in alpha, read more [here](https://arize.com/docs/ax/rest-reference#api-version-stages).
## OpenAPI
````yaml https://api.arize.com/v2/spec.yaml delete /v2/spans
openapi: 3.0.3
info:
title: Arize REST API
version: 2.0.0
description: |
API specification for the backend data server. The API is hosted globally
at https://api.arize.com/v2 or in your own environment.
license:
name: Apache-2.0
url: https://www.apache.org/licenses/LICENSE-2.0
servers:
- description: Global
url: https://api.arize.com
- description: Regional
url: https://api.{region}.arize.com
variables:
region:
default: eu-west-1a
enum:
- eu-west-1a
- ca-central-1a
- description: Custom Host
url: https://{host}
variables:
host:
default: api.arize.com
security:
- bearerAuth: []
tags:
- name: AI Integrations
description: |
AI integrations configure access to external LLM providers (e.g. OpenAI,
Azure OpenAI, AWS Bedrock, Vertex AI). Integrations can be scoped to the
entire account, a specific organization, or a specific space.
- name: Annotation Configs
description: >
Annotation configs allow you to define consistent annotation schemas that
can be reused across your workspace, ensuring evaluations are structured
and
comparable over time.
- name: Annotation Queues
description: >
Annotation queues help you organize and manage human evaluation workflows.
Use queues to assign spans or examples to annotators for review and
labeling.
- name: API Keys
description: >
API keys are used to authenticate requests to the Arize API. List your
keys
to view metadata; the raw secret is never returned after creation.
- name: Datasets
description: |
Datasets are structured, version-controlled example collections you use to
run, evaluate, and track LLM experiments.
- name: Evaluators
description: >
Evaluators are reusable evaluation configurations used to assess the
quality
of LLM outputs. They can be template-based (using LLM judges) or
code-based.
- name: Experiments
description: >
Experiments let you systematically test prompt/model changes using
datasets,
tasks, and evaluators.
- name: Integrations
description: >
Integrations configure access to external LLM providers (e.g. OpenAI,
Azure OpenAI, AWS Bedrock, Vertex AI), notifications services (e.g.
PagerDuty, Slack), and
your own agents. Integrations can be scoped to the entire account, a
specific
organization, or a specific space.
- name: Organizations
description: >
Organizations are top-level containers within an Arize AX account for
grouping spaces.
- name: Projects
description: |
Projects represent LLM applications being monitored in Arize where you can
observe traces and spans.
- name: Prompts
description: >
Prompts are reusable, versioned templates for LLM interactions. Use
prompts
to standardize and manage how you interact with LLMs across your
application.
- name: Resource Restrictions
description: |
Endpoints for restricting and unrestricting resources (projects, models).
- name: Role Bindings
description: |
Role bindings assign a role to a user on a resource. REST currently
supports space- and project-scoped bindings.
- name: Roles
description: >
Roles define sets of permissions that can be assigned to users within an
account. Create custom roles to tailor access control to your team's
needs.
- name: Spaces
description: >
Spaces are containers within an organization for grouping related
projects,
datasets, and experiments, enabling collaboration or isolated
experimentation
with role-based access control.
- name: Spans
description: |
Spans represent individual operations within a trace. A span captures the
timing, status, and attributes of a single operation in your application.
- name: Tasks
description: |
Tasks are configurable units of work that tie one or more evaluators to a
data source (project or dataset). Use tasks to automate evaluation of LLM
outputs, with support for continuous evaluation and backfill runs.
- name: Users
description: >
Users represent members of an account. The Users endpoints allow creating,
listing, updating (display name), and removing users from the account
programmatically.
paths:
/v2/spans:
delete:
tags:
- Spans
summary: Delete spans
description: >
Permanently deletes spans by their span IDs. This operation is
irreversible.
Accepts between 1 and 5000 span IDs per request. Only spans within the
supported lookback window (2 years) are considered; older spans are not
affected.
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 lookback window, or not reached when `completed` is `false`.
The delete operation is idempotent — re-submitting already-deleted IDs
is safe.
This endpoint is in alpha, read more
[here](https://arize.com/docs/ax/rest-reference#api-version-stages).
operationId: spans_delete
requestBody:
$ref: '#/components/requestBodies/DeleteSpansRequestBody'
responses:
'200':
$ref: '#/components/responses/SpanDeleteSuccess'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'422':
$ref: '#/components/responses/UnprocessableEntity'
'429':
$ref: '#/components/responses/RateLimitExceeded'
'503':
$ref: '#/components/responses/SpanDeleteError'
components:
requestBodies:
DeleteSpansRequestBody:
description: Body containing span IDs to delete
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/DeleteSpansRequest'
example:
project_id: UHJvamVjdDox
span_ids:
- a1b2c3d4e5f6a7b8
- f8e7d6c5b4a39281
responses:
SpanDeleteSuccess:
description: >
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`.
content:
application/json:
schema:
$ref: '#/components/schemas/SpanDeleteResponse'
examples:
full_success:
summary: All requested spans deleted
value:
completed: true
deleted_span_ids:
- a1b2c3d4e5f6a7b8
- b2c3d4e5f6a7b8c9
not_deleted_span_ids: []
some_not_found:
summary: Some spans were not found
value:
completed: true
deleted_span_ids:
- a1b2c3d4e5f6a7b8
not_deleted_span_ids:
- c3d4e5f6a7b8c9d0
incomplete:
summary: Incomplete — retry required
value:
completed: false
deleted_span_ids:
- a1b2c3d4e5f6a7b8
not_deleted_span_ids:
- b2c3d4e5f6a7b8c9
BadRequest:
description: Invalid request
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
example:
status: 400
title: Invalid request parameters
detail: The 'name' field is required and must be a non-empty string.
instance: /resource
type: https://arize.com/docs/ax/rest-reference/errors#invalid-request
Unauthorized:
description: Authentication is required
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
example:
status: 401
title: Authentication required
detail: You must be authenticated to access this resource.
instance: /resource
type: >-
https://arize.com/docs/ax/rest-reference/errors#authentication-required
Forbidden:
description: Insufficient permissions to access this resource
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
example:
status: 403
title: Access forbidden
detail: You do not have permission to access this resource.
instance: /resource/12345
type: https://arize.com/docs/ax/rest-reference/errors#access-forbidden
NotFound:
description: Not found
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
example:
status: 404
title: Resource not found
detail: The requested resource with ID '12345' was not found.
instance: /resource/12345
type: https://arize.com/docs/ax/rest-reference/errors#resource-not-found
UnprocessableEntity:
description: Unprocessable entity
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
example:
status: 422
title: Unprocessable Entity
detail: Minimum score must be less than maximum score.
instance: /annotation-configs
type: >-
https://arize.com/docs/ax/rest-reference/errors#unprocessable-entity
RateLimitExceeded:
description: Rate limit exceeded
headers:
Retry-After:
description: |
When throttled (429), how long to wait before retrying. Value is
either a delta-seconds integer.
schema:
type: integer
minimum: 0
example: 42
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
example:
status: 429
title: Rate limit exceeded
detail: >-
You have exceeded the allowed number of requests. Please try again
later.
instance: /resource
type: >-
https://arize.com/docs/ax/rest-reference/errors#rate-limit-exceeded
SpanDeleteError:
description: |
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.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/SpanDeleteProblem'
example:
status: 503
title: Service Unavailable
detail: >-
Result incomplete: inspect deleted_span_ids, then retry the full
request.
type: >-
https://arize.com/docs/ax/rest-reference/errors#service-unavailable
deleted_span_ids:
- a1b2c3d4e5f6a7b8
not_deleted_span_ids:
- b2c3d4e5f6a7b8c9
schemas:
DeleteSpansRequest:
type: object
required:
- project_id
- span_ids
additionalProperties: false
properties:
project_id:
type: string
description: The project ID containing the spans to delete
span_ids:
type: array
items:
type: string
minItems: 1
maxItems: 5000
description: List of span IDs to delete (maximum 5000)
SpanDeleteResponse:
type: object
description: >
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.
required:
- completed
- deleted_span_ids
- not_deleted_span_ids
properties:
completed:
type: boolean
description: >
`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:
type: array
items:
type: string
description: Span IDs confirmed deleted in this request.
not_deleted_span_ids:
type: array
items:
type: string
description: >
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.
additionalProperties: false
Problem:
type: object
description: RFC 9457 Problem Details
properties:
title:
type: string
description: A short, human-readable summary of the problem type
status:
type: integer
description: >-
The HTTP status code generated by the origin server for this
occurrence of the problem
type:
type: string
format: uri-reference
description: A URI reference that identifies the problem type
detail:
type: string
description: >-
A human-readable explanation specific to this occurrence of the
problem
instance:
type: string
format: uri-reference
description: >-
A URI reference that identifies the specific occurrence of the
problem
required:
- title
- status
additionalProperties: false
SpanDeleteProblem:
description: >
RFC 9457 Problem Details extended with span delete context. Returned
when the
request fails after partially completing, so the caller knows which IDs
were
already deleted and which still need to be retried. The delete operation
is
idempotent — retrying the original full request is safe.
allOf:
- $ref: '#/components/schemas/Problem'
- type: object
properties:
deleted_span_ids:
type: array
items:
type: string
description: >
Span IDs confirmed deleted before the failure occurred. Safe to
include
or omit on retry, as the delete operation is idempotent.
not_deleted_span_ids:
type: array
items:
type: string
description: >
Span IDs that were not deleted before the failure occurred.
Retry the
original request to attempt deletion of these IDs.
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat:
description: >
Most Arize AI endpoints require authentication. For those endpoints that
require authentication, include your API key in the request header using
the format
``` Authorization: Bearer
```
````