---
title: "Delete traces (async)"
method: POST
path: "/v1/projects/{projectSlug}/trace-deletions"
tags: ["Trace deletions"]
---

# Delete traces (async)

`POST /v1/projects/{projectSlug}/trace-deletions`

## Request

- Base URL: `https://api.latitude.so`
- URL: `https://api.latitude.so/v1/projects/{projectSlug}/trace-deletions`
- Auth: HTTP bearer

Permanently deletes the traces selected by `traces`, together with everything derived from them: their spans, scores and annotations, search indexes, and the analyses of the sessions they belong to. The deletion runs in the background; poll it with `getTraceDeletion` until `status` is `completed`. Deletion cannot be undone. Use `previewTraceDeletion` first to see how many traces a selector matches.

## Path parameters

- `projectSlug` string, required: Project slug (human-readable identifier)

## Request body

- CreateTraceDeletionBody
  - `traces` union, required
    - object: Which traces to delete: up to 100 explicit trace ids, or a trace filter set (for example every trace tagged `customer:acme`, or every trace of one `userId`). A filter must contain at least one condition, and percentile conditions are not accepted. Only traces that started before the deletion is requested are deleted.
      - `by` 'ids', required: Match an explicit list of traces by their identifiers. Pair with `ids`.
      - `ids` string[], required: Non-empty list of trace identifiers.
    - object: Which traces to delete: up to 100 explicit trace ids, or a trace filter set (for example every trace tagged `customer:acme`, or every trace of one `userId`). A filter must contain at least one condition, and percentile conditions are not accepted. Only traces that started before the deletion is requested are deleted.
      - `by` 'filters', required: Match every trace produced by a filter set. Pair with `filters`; result count is not bounded.
      - `filters` FilterSet, required: Filter set keyed by field name. Each entry holds an array of conditions ANDed together for that field; field-level groups are also ANDed across the set.
  - `includeDatasetRows` boolean: Also delete dataset rows that were copied from the deleted traces, in every dataset of the organization, including their earlier versions. Defaults to `false`, which keeps dataset rows. Ignored by `previewTraceDeletion`.

## Response `202`

Trace deletion requested

- TraceDeletion
  - `id` string, required: Trace deletion identifier. Use it to poll the deletion with `getTraceDeletion`.
  - `status` 'pending' | 'running' | 'completed' | 'failed', required: `pending` until work starts, `running` while traces are being deleted, then `completed` or `failed`. Deletion is irreversible: traces deleted before a failure stay deleted.
  - `filters` object, required: The trace filter the deletion selects with, including any explicit trace ids as a `traceId` condition. Only traces that started before `createdAt` are deleted.
  - `includeDatasetRows` boolean, required: Whether dataset rows copied from the deleted traces are deleted too.
  - `requestedBy` object, required: Who requested the deletion.
    - `type` 'user' | 'api_key' | 'staff', required: `user` for a person, `api_key` for an API key, `staff` for Latitude support.
    - `id` string, required: Identifier of the user or API key that requested the deletion.
  - `matchedTraceCount` integer, required: Traces deleted so far. Final once `status` is `completed` or `failed`.
  - `deletedRecordCount` integer, required: Records deleted so far across the traces, their spans, and everything derived from them (scores, annotations, search indexes, session analyses).
  - `error` string, nullable, required: Why the deletion failed. `null` unless `status` is `failed`.
  - `createdAt` string, required: ISO-8601 time the deletion was requested.
  - `startedAt` string, nullable, required: ISO-8601 time work started, or `null` while pending.
  - `completedAt` string, nullable, required: ISO-8601 time the deletion completed or failed, or `null` while it is still in progress.

## Other responses

- `400`: Validation error
- `401`: Unauthorized
- `404`: Not found

## Changes

- **2026-10-27** `0685be1cbf9f`: 2 info
  - added the new optional request property `includeDatasetRows`
  - added the required property `includeDatasetRows` to the response with the `202` status
- **2026-10-27** `15073decd632`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/latitude-dev/apis/latitude/changes/v1/projects/:projectSlug/trace-deletions/post.md)

---

[API](https://skmtc.dev/latitude-dev/apis/latitude.md) - [All operations](https://skmtc.dev/latitude-dev/apis/latitude/llms.txt) - [OpenAPI document](https://skmtc.dev/latitude-dev/apis/latitude/revisions/0685be1cbf9f?raw)