Deleting spans using the API

Last updated: December 11, 2025

Prerequisites

Plans: Any

Deployments: Any

Use case

You can delete individual traces programmatically by making a POST request to the Braintrust API /v1/project_logs/{project_id}/insert endpoint (reference). The JSON body of this request containing an events array. Each element in events is the object you want to delete: at minimum its id, plus "_object_delete": true .

Delete one or more spans

Step 1: Identify the correct API base URL

Braintrust hosted data plane: use https://api.braintrust.dev

Hybrid data plane: use your organization's custom data plane URL

Step 2: Query for the span you want to delete

Use BTQL to find the specific span(s) you want to delete by their span IDs

Step 3: Delete the span(s) by making a POST request to the Braintrust API /v1/project_logs/{project_id}/insert endpoint.

Include a JSON body containing an events array, where each element represents the object to delete, including at minimum its id and "_object_delete": true.
Example JSON body:

{
  "events": [
    {
      "id": "span_id_to_delete",
      "_object_delete": true
    }
  ]
}

Example code

Delete all spans from a trace (Python)

import requests

btql_url = "https://api.braintrust.dev/btql"
project = 'your-project-id'
insert_url = "https://api.braintrust.dev/v1/project_logs/"+project+"/insert"
headers = {
    "Authorization": "Bearer sk-your-api-keys",
    "Content-Type": "application/json"
}

def get_ids_from_trace(project_id,root_span_id):
    data = {
        "query": (
            "select: id\n"
            "from: project_logs('"+project_id+"')\n"
            "filter: root_span_id='"+root_span_id+"'"
        ),
        "use_brainstore": True,
        "brainstore_realtime": True
    }

    response = requests.post(btql_url, headers=headers, json=data)
    ids = response.json()['data']
    return ids

def delete_spans(span_ids):
    events = []
    for span in range(0, len(span_ids)):
        events.append(span_ids[span])
        events[span]['_object_delete'] = True
    
    data = {"events": events}

    response = requests.post(insert_url, headers=headers, json=data)
    return response.json()

def main():
    root_span_id = 'your-root-span-id'
    ids_to_delete = get_ids_from_trace(project,root_span_id)
    deleted_spans = delete_spans(ids_to_delete)
    print("Deleted spans: "+ str(deleted_spans))

if __name__ == "__main__":
    main()