Skip to Content

Delete traces in bulk

POSThttps://api.respan.ai/api/traces/bulk/

Delete traces matching a non-empty filter object. The endpoint resolves at most 1,000 trace IDs per request; requests matching more are rejected with 422. Use the query parameters for the canonical environment and time window; the same fields in the body only narrow that window. Only the documented filter fields and metadata__<key> are supported. Unknown fields and invalid operators return 400 before anything is deleted. ClickHouse deletion is asynchronous, so success_count and deleted_count report traces submitted for deletion, not confirmation that every row has already disappeared. Rate limit: 10 requests per minute per organization and exact endpoint path for API-key calls (shared across API keys), and per user and exact endpoint path for JWT calls.

Servers

https://api.respan.ai: Respan API Server

Authentication

RespanApiKey

Use your Respan API key for Respan API authentication. Enter only the Respan API key value; clients send Authorization: Bearer <RESPAN_API_KEY>. For /api/responses, provider credentials such as Perplexity, OpenAI, or Azure OpenAI go in Settings -> Providers or respan_params.credential_override in the request body, not in this authentication field.

HTTP scheme: bearer; format: Respan API key.

HTTP
Authorization: Bearer $RESPAN_API_KEY

Or:

DashboardJwt

Use a dashboard JWT only for dashboard-authenticated endpoints. Respan API-key endpoints use the respanApiKey auth field instead.

HTTP scheme: bearer; format: Dashboard JWT.

HTTP
Authorization: Bearer $RESPAN_DASHBOARD_JWT

Query parameters

Parameter Type Required Description and constraints
start_time string Optional
Start of time range (ISO 8601). Defaults to one hour before end_time when omitted.
Format: date-time
Example: "2025-01-01T00:00:00Z"
end_time string Optional
End of time range (ISO 8601). Defaults to now when omitted.
Format: date-time
Example: "2025-01-31T23:59:59Z"
environment string Optional
Filter by environment.
Example: "prod"

Request body

A request body is required.

application/json

Field Type Requirement Description and constraints
$ object Required body
-
filters object Required in parent
Required. Selects the traces to delete.

Each key is a field to filter on, and each value is a condition: {"<field>": {"operator": "<operator>", "value": [...]}}. A trace must match every condition. To set two conditions on one field, such as a range, pass a list of conditions.

Operators: "" (equals, the default), not, in, not_in, lt, lte, gt, gte, contains, not_contains, icontains (ignores case), startswith, not_startswith, endswith, not_endswith, empty, not_empty. Put values in a list: "" and in match any of the listed values, and not and not_in match none of them. Other operators take one value; for empty and not_empty, send [""].

Fields: trace_unique_id, customer_identifier, environment, start_time, end_time, span_count, llm_call_count, error_count, total_cost, total_prompt_tokens, total_completion_tokens, total_tokens, and metadata__<key> (values are strings). Here environment, start_time and end_time only narrow the window set by the query parameters. Unsupported fields or operators return a 400 error, and nothing is deleted.

Example:

json<br />{<br /> "trace_unique_id": {"operator": "in", "value": ["trace-01", "trace-02"]}<br />}<br />
Reference: #/components/schemas/TraceBulkDeleteFilters
Minimum properties: 1
Example: {"customer_identifier":{"operator":"","value":["customer-123"]}}
filters.trace_unique_id object Optional
A trace filter condition. Use is for an exact value or in for any value in a list.
Reference: #/components/schemas/TraceFilterCondition
Additional properties are not allowed
Example: {"operator":"in","value":["trace-01","trace-02"]}
filters.trace_unique_id.operator string Optional
Comparison operator. If omitted or empty, exact matching is used.
Allowed: "", "not", "in", "not_in", "lt", "lte", "gt", "gte", "contains", "not_contains", "icontains", "startswith", "not_startswith", "endswith", "not_endswith", "empty", "notEmpty", "not_empty", "isnull"
Default: “
filters.trace_unique_id.value array<any> Required in parent
One or more values used by the comparison.
Minimum items: 1
filters.trace_unique_id.value[] any Array item
-
filters.unique_organization_id object Optional
A trace filter condition. Use is for an exact value or in for any value in a list.
Reference: #/components/schemas/TraceFilterCondition
Additional properties are not allowed
Example: {"operator":"in","value":["trace-01","trace-02"]}
filters.unique_organization_id.operator string Optional
Comparison operator. If omitted or empty, exact matching is used.
Allowed: "", "not", "in", "not_in", "lt", "lte", "gt", "gte", "contains", "not_contains", "icontains", "startswith", "not_startswith", "endswith", "not_endswith", "empty", "notEmpty", "not_empty", "isnull"
Default: “
filters.unique_organization_id.value array<any> Required in parent
One or more values used by the comparison.
Minimum items: 1
filters.unique_organization_id.value[] any Array item
-
filters.environment object Optional
A trace filter condition. Use is for an exact value or in for any value in a list.
Reference: #/components/schemas/TraceFilterCondition
Additional properties are not allowed
Example: {"operator":"in","value":["trace-01","trace-02"]}
filters.environment.operator string Optional
Comparison operator. If omitted or empty, exact matching is used.
Allowed: "", "not", "in", "not_in", "lt", "lte", "gt", "gte", "contains", "not_contains", "icontains", "startswith", "not_startswith", "endswith", "not_endswith", "empty", "notEmpty", "not_empty", "isnull"
Default: “
filters.environment.value array<any> Required in parent
One or more values used by the comparison.
Minimum items: 1
filters.environment.value[] any Array item
-
filters.start_time object Optional
A trace filter condition. Use is for an exact value or in for any value in a list.
Reference: #/components/schemas/TraceFilterCondition
Additional properties are not allowed
Example: {"operator":"in","value":["trace-01","trace-02"]}
filters.start_time.operator string Optional
Comparison operator. If omitted or empty, exact matching is used.
Allowed: "", "not", "in", "not_in", "lt", "lte", "gt", "gte", "contains", "not_contains", "icontains", "startswith", "not_startswith", "endswith", "not_endswith", "empty", "notEmpty", "not_empty", "isnull"
Default: “
filters.start_time.value array<any> Required in parent
One or more values used by the comparison.
Minimum items: 1
filters.start_time.value[] any Array item
-
filters.end_time object Optional
A trace filter condition. Use is for an exact value or in for any value in a list.
Reference: #/components/schemas/TraceFilterCondition
Additional properties are not allowed
Example: {"operator":"in","value":["trace-01","trace-02"]}
filters.end_time.operator string Optional
Comparison operator. If omitted or empty, exact matching is used.
Allowed: "", "not", "in", "not_in", "lt", "lte", "gt", "gte", "contains", "not_contains", "icontains", "startswith", "not_startswith", "endswith", "not_endswith", "empty", "notEmpty", "not_empty", "isnull"
Default: “
filters.end_time.value array<any> Required in parent
One or more values used by the comparison.
Minimum items: 1
filters.end_time.value[] any Array item
-
filters.span_count object Optional
A trace filter condition. Use is for an exact value or in for any value in a list.
Reference: #/components/schemas/TraceFilterCondition
Additional properties are not allowed
Example: {"operator":"in","value":["trace-01","trace-02"]}
filters.span_count.operator string Optional
Comparison operator. If omitted or empty, exact matching is used.
Allowed: "", "not", "in", "not_in", "lt", "lte", "gt", "gte", "contains", "not_contains", "icontains", "startswith", "not_startswith", "endswith", "not_endswith", "empty", "notEmpty", "not_empty", "isnull"
Default: “
filters.span_count.value array<any> Required in parent
One or more values used by the comparison.
Minimum items: 1
filters.span_count.value[] any Array item
-
filters.llm_call_count object Optional
A trace filter condition. Use is for an exact value or in for any value in a list.
Reference: #/components/schemas/TraceFilterCondition
Additional properties are not allowed
Example: {"operator":"in","value":["trace-01","trace-02"]}
filters.llm_call_count.operator string Optional
Comparison operator. If omitted or empty, exact matching is used.
Allowed: "", "not", "in", "not_in", "lt", "lte", "gt", "gte", "contains", "not_contains", "icontains", "startswith", "not_startswith", "endswith", "not_endswith", "empty", "notEmpty", "not_empty", "isnull"
Default: “
filters.llm_call_count.value array<any> Required in parent
One or more values used by the comparison.
Minimum items: 1
filters.llm_call_count.value[] any Array item
-
filters.total_cost object Optional
A trace filter condition. Use is for an exact value or in for any value in a list.
Reference: #/components/schemas/TraceFilterCondition
Additional properties are not allowed
Example: {"operator":"in","value":["trace-01","trace-02"]}
filters.total_cost.operator string Optional
Comparison operator. If omitted or empty, exact matching is used.
Allowed: "", "not", "in", "not_in", "lt", "lte", "gt", "gte", "contains", "not_contains", "icontains", "startswith", "not_startswith", "endswith", "not_endswith", "empty", "notEmpty", "not_empty", "isnull"
Default: “
filters.total_cost.value array<any> Required in parent
One or more values used by the comparison.
Minimum items: 1
filters.total_cost.value[] any Array item
-
filters.total_prompt_tokens object Optional
A trace filter condition. Use is for an exact value or in for any value in a list.
Reference: #/components/schemas/TraceFilterCondition
Additional properties are not allowed
Example: {"operator":"in","value":["trace-01","trace-02"]}
filters.total_prompt_tokens.operator string Optional
Comparison operator. If omitted or empty, exact matching is used.
Allowed: "", "not", "in", "not_in", "lt", "lte", "gt", "gte", "contains", "not_contains", "icontains", "startswith", "not_startswith", "endswith", "not_endswith", "empty", "notEmpty", "not_empty", "isnull"
Default: “
filters.total_prompt_tokens.value array<any> Required in parent
One or more values used by the comparison.
Minimum items: 1
filters.total_prompt_tokens.value[] any Array item
-
filters.total_completion_tokens object Optional
A trace filter condition. Use is for an exact value or in for any value in a list.
Reference: #/components/schemas/TraceFilterCondition
Additional properties are not allowed
Example: {"operator":"in","value":["trace-01","trace-02"]}
filters.total_completion_tokens.operator string Optional
Comparison operator. If omitted or empty, exact matching is used.
Allowed: "", "not", "in", "not_in", "lt", "lte", "gt", "gte", "contains", "not_contains", "icontains", "startswith", "not_startswith", "endswith", "not_endswith", "empty", "notEmpty", "not_empty", "isnull"
Default: “
filters.total_completion_tokens.value array<any> Required in parent
One or more values used by the comparison.
Minimum items: 1
filters.total_completion_tokens.value[] any Array item
-
filters.total_tokens object Optional
A trace filter condition. Use is for an exact value or in for any value in a list.
Reference: #/components/schemas/TraceFilterCondition
Additional properties are not allowed
Example: {"operator":"in","value":["trace-01","trace-02"]}
filters.total_tokens.operator string Optional
Comparison operator. If omitted or empty, exact matching is used.
Allowed: "", "not", "in", "not_in", "lt", "lte", "gt", "gte", "contains", "not_contains", "icontains", "startswith", "not_startswith", "endswith", "not_endswith", "empty", "notEmpty", "not_empty", "isnull"
Default: “
filters.total_tokens.value array<any> Required in parent
One or more values used by the comparison.
Minimum items: 1
filters.total_tokens.value[] any Array item
-
filters.error_count object Optional
A trace filter condition. Use is for an exact value or in for any value in a list.
Reference: #/components/schemas/TraceFilterCondition
Additional properties are not allowed
Example: {"operator":"in","value":["trace-01","trace-02"]}
filters.error_count.operator string Optional
Comparison operator. If omitted or empty, exact matching is used.
Allowed: "", "not", "in", "not_in", "lt", "lte", "gt", "gte", "contains", "not_contains", "icontains", "startswith", "not_startswith", "endswith", "not_endswith", "empty", "notEmpty", "not_empty", "isnull"
Default: “
filters.error_count.value array<any> Required in parent
One or more values used by the comparison.
Minimum items: 1
filters.error_count.value[] any Array item
-
filters.customer_identifier object Optional
A trace filter condition. Use is for an exact value or in for any value in a list.
Reference: #/components/schemas/TraceFilterCondition
Additional properties are not allowed
Example: {"operator":"in","value":["trace-01","trace-02"]}
filters.customer_identifier.operator string Optional
Comparison operator. If omitted or empty, exact matching is used.
Allowed: "", "not", "in", "not_in", "lt", "lte", "gt", "gte", "contains", "not_contains", "icontains", "startswith", "not_startswith", "endswith", "not_endswith", "empty", "notEmpty", "not_empty", "isnull"
Default: “
filters.customer_identifier.value array<any> Required in parent
One or more values used by the comparison.
Minimum items: 1
filters.customer_identifier.value[] any Array item
-
filters.<key> object Map value
A trace filter condition. Use is for an exact value or in for any value in a list.
Reference: #/components/schemas/TraceFilterCondition
Additional properties are not allowed
Example: {"operator":"in","value":["trace-01","trace-02"]}
filters.<key>.operator string Optional
Comparison operator. If omitted or empty, exact matching is used.
Allowed: "", "not", "in", "not_in", "lt", "lte", "gt", "gte", "contains", "not_contains", "icontains", "startswith", "not_startswith", "endswith", "not_endswith", "empty", "notEmpty", "not_empty", "isnull"
Default: “
filters.<key>.value array<any> Required in parent
One or more values used by the comparison.
Minimum items: 1
filters.<key>.value[] any Array item
-

OpenAPI request schema

{
  "type": "object",
  "required": [
    "filters"
  ],
  "properties": {
    "filters": {
      "$ref": "#/components/schemas/TraceBulkDeleteFilters"
    }
  }
}
Delete traces for one customer
JSON
{ "filters": { "customer_identifier": { "operator": "", "value": [ "customer-123" ] } } }
Delete selected trace IDs
JSON
{ "filters": { "trace_unique_id": { "operator": "in", "value": [ "trace-01", "trace-02" ] } } }

Examples

Delete traces for one customer

Headers

JSON
{ "Authorization": "Bearer YOUR_RESPAN_API_KEY" }

Query parameters

JSON
{ "start_time": "2025-01-01T00:00:00Z", "end_time": "2025-01-31T23:59:59Z", "environment": "prod" }

Request

JSON
{ "filters": { "customer_identifier": { "operator": "", "value": [ "customer-123" ] } } }

Response

JSON
{ "body": { "success_count": 42, "error_count": 0, "errors": [], "deleted_count": 42, "message": "Successfully deleted 42 traces" } }

Delete selected trace IDs

Headers

JSON
{ "Authorization": "Bearer YOUR_RESPAN_API_KEY" }

Query parameters

JSON
{ "start_time": "2025-01-01T00:00:00Z", "end_time": "2025-01-31T23:59:59Z", "environment": "prod" }

Request

JSON
{ "filters": { "trace_unique_id": { "operator": "in", "value": [ "trace-01", "trace-02" ] } } }

Response

JSON
{ "body": { "success_count": 42, "error_count": 0, "errors": [], "deleted_count": 42, "message": "Successfully deleted 42 traces" } }

Responses

200

Traces were matched and submitted for asynchronous deletion.

application/json

Field Type Requirement Description and constraints
$ object and object Body
Canonical bulk result envelope plus delete-specific fields.
Reference: #/components/schemas/BulkDeleteResponse
$ (allOf 1) object Schema variant
Canonical result envelope for a bulk operation.
Reference: #/components/schemas/BulkOperationResponse
Example: {"success_count":1,"error_count":0,"errors":[]}
$ (allOf 1).success_count integer Required in parent
Number of items successfully processed.
Minimum: 0
$ (allOf 1).error_count integer Required in parent
Number of items that failed.
Minimum: 0
$ (allOf 1).errors array<object> Required in parent
Item-level failures, keyed by zero-based input index.
$ (allOf 1).errors[] object Array item
An item that failed during a bulk operation. index is zero-based and identifies the corresponding item in the request array.
Reference: #/components/schemas/BulkItemError
$ (allOf 1).errors[].index integer Required in parent
Zero-based index of the failed item in the submitted array.
Minimum: 0
$ (allOf 1).errors[].error string Required in parent
Error message for the failed item.
$ (allOf 2) object Schema variant
-
$ (allOf 2).deleted_count integer Required in parent
Number of resources matched and processed for deletion.
Minimum: 0
$ (allOf 2).message string Required in parent
Human-readable deletion result.

OpenAPI response schema

{
  "$ref": "#/components/schemas/BulkDeleteResponse"
}
Matching traces submitted for deletion
JSON
{ "success_count": 42, "error_count": 0, "errors": [], "deleted_count": 42, "message": "Successfully deleted 42 traces" }
No matching traces
JSON
{ "success_count": 0, "error_count": 0, "errors": [], "deleted_count": 0, "message": "No traces matched the given filters" }

400

The request body is missing filters, filters is empty, or it uses an unknown field or invalid operator.

application/json

Field Type Requirement Description and constraints
$ object Body
-
filters array<string> Required in parent
-
filters[] string Array item
-

OpenAPI response schema

{
  "type": "object",
  "required": [
    "filters"
  ],
  "properties": {
    "filters": {
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  }
}
Missing filters field
JSON
{ "filters": [ "This field is required." ] }
Empty filters object
JSON
{ "filters": [ "Must be a non-empty filter dict." ] }

403

The API key is missing, invalid or expired, or it can’t delete traces.

application/json

Field Type Requirement Description and constraints
$ object Body
-
detail string Required in parent
-

OpenAPI response schema

{
  "type": "object",
  "required": [
    "detail"
  ],
  "properties": {
    "detail": {
      "type": "string"
    }
  }
}
Example
JSON
{ "detail": "Your API key is invalid or expired, please check your API key in the platform settings." }

422

The filters matched more than 1,000 traces. Narrow the filters and retry.

application/json

Field Type Requirement Description and constraints
$ object Body
-
detail string Required in parent
-

OpenAPI response schema

{
  "type": "object",
  "required": [
    "detail"
  ],
  "properties": {
    "detail": {
      "type": "string"
    }
  }
}
Example
JSON
{ "detail": "Cannot process more than 1000 items at once." }

429

Rate limit exceeded.

application/json

Field Type Requirement Description and constraints
$ object Body
-
detail string Required in parent
-
retry_after integer Optional
Seconds to wait before retrying.
Minimum: 0

OpenAPI response schema

{
  "type": "object",
  "required": [
    "detail"
  ],
  "properties": {
    "detail": {
      "type": "string"
    },
    "retry_after": {
      "type": "integer",
      "minimum": 0,
      "description": "Seconds to wait before retrying."
    }
  }
}
Example
JSON
{ "detail": "Rate limit exceeded", "retry_after": 30 }

500

Internal Server Error

application/json

Field Type Requirement Description and constraints
$ object Body
-
error string Optional
Example: "Internal server error"

OpenAPI response schema

{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "example": "Internal server error"
    }
  }
}

OpenAPI source

The operation and referenced components below retain the complete OpenAPI definitions, including constraints and examples.

OpenAPI operation

{
  "summary": "Delete traces in bulk",
  "operationId": "bulkDeleteTraces",
  "tags": [
    "Traces"
  ],
  "description": "Delete traces matching a non-empty filter object. The endpoint resolves at most 1,000 trace IDs per request; requests matching more are rejected with `422`. Use the query parameters for the canonical environment and time window; the same fields in the body only narrow that window. Only the documented filter fields and `metadata__<key>` are supported. Unknown fields and invalid operators return `400` before anything is deleted. ClickHouse deletion is asynchronous, so `success_count` and `deleted_count` report traces submitted for deletion, not confirmation that every row has already disappeared. Rate limit: 10 requests per minute per organization and exact endpoint path for API-key calls (shared across API keys), and per user and exact endpoint path for JWT calls.",
  "parameters": [
    {
      "name": "start_time",
      "in": "query",
      "schema": {
        "type": "string",
        "format": "date-time"
      },
      "description": "Start of time range (ISO 8601). Defaults to one hour before `end_time` when omitted.",
      "example": "2025-01-01T00:00:00Z"
    },
    {
      "name": "end_time",
      "in": "query",
      "schema": {
        "type": "string",
        "format": "date-time"
      },
      "description": "End of time range (ISO 8601). Defaults to now when omitted.",
      "example": "2025-01-31T23:59:59Z"
    },
    {
      "name": "environment",
      "in": "query",
      "schema": {
        "type": "string"
      },
      "description": "Filter by environment.",
      "example": "prod"
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "required": [
            "filters"
          ],
          "properties": {
            "filters": {
              "$ref": "#/components/schemas/TraceBulkDeleteFilters"
            }
          }
        },
        "examples": {
          "byCustomer": {
            "summary": "Delete traces for one customer",
            "value": {
              "filters": {
                "customer_identifier": {
                  "operator": "",
                  "value": [
                    "customer-123"
                  ]
                }
              }
            }
          },
          "byTraceIds": {
            "summary": "Delete selected trace IDs",
            "value": {
              "filters": {
                "trace_unique_id": {
                  "operator": "in",
                  "value": [
                    "trace-01",
                    "trace-02"
                  ]
                }
              }
            }
          }
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Traces were matched and submitted for asynchronous deletion.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/BulkDeleteResponse"
          },
          "examples": {
            "success": {
              "summary": "Matching traces submitted for deletion",
              "value": {
                "success_count": 42,
                "error_count": 0,
                "errors": [],
                "deleted_count": 42,
                "message": "Successfully deleted 42 traces"
              }
            },
            "noMatches": {
              "summary": "No matching traces",
              "value": {
                "success_count": 0,
                "error_count": 0,
                "errors": [],
                "deleted_count": 0,
                "message": "No traces matched the given filters"
              }
            }
          }
        }
      }
    },
    "400": {
      "description": "The request body is missing `filters`, `filters` is empty, or it uses an unknown field or invalid operator.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "filters"
            ],
            "properties": {
              "filters": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            }
          },
          "examples": {
            "missingFilters": {
              "summary": "Missing filters field",
              "value": {
                "filters": [
                  "This field is required."
                ]
              }
            },
            "emptyFilters": {
              "summary": "Empty filters object",
              "value": {
                "filters": [
                  "Must be a non-empty filter dict."
                ]
              }
            }
          }
        }
      }
    },
    "403": {
      "description": "The API key is missing, invalid or expired, or it can't delete traces.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "detail"
            ],
            "properties": {
              "detail": {
                "type": "string"
              }
            }
          },
          "example": {
            "detail": "Your API key is invalid or expired, please check your API key in the platform settings."
          }
        }
      }
    },
    "422": {
      "description": "The filters matched more than 1,000 traces. Narrow the filters and retry.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "detail"
            ],
            "properties": {
              "detail": {
                "type": "string"
              }
            }
          },
          "example": {
            "detail": "Cannot process more than 1000 items at once."
          }
        }
      }
    },
    "429": {
      "description": "Rate limit exceeded.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "detail"
            ],
            "properties": {
              "detail": {
                "type": "string"
              },
              "retry_after": {
                "type": "integer",
                "minimum": 0,
                "description": "Seconds to wait before retrying."
              }
            }
          },
          "example": {
            "detail": "Rate limit exceeded",
            "retry_after": 30
          }
        }
      }
    },
    "500": {
      "description": "Internal Server Error",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "string",
                "example": "Internal server error"
              }
            }
          }
        }
      }
    }
  },
  "security": [
    {
      "RespanApiKey": []
    },
    {
      "DashboardJwt": []
    }
  ],
  "x-fern-examples": [
    {
      "name": "Delete traces for one customer",
      "query-parameters": {
        "start_time": "2025-01-01T00:00:00Z",
        "end_time": "2025-01-31T23:59:59Z",
        "environment": "prod"
      },
      "request": {
        "filters": {
          "customer_identifier": {
            "operator": "",
            "value": [
              "customer-123"
            ]
          }
        }
      },
      "response": {
        "body": {
          "success_count": 42,
          "error_count": 0,
          "errors": [],
          "deleted_count": 42,
          "message": "Successfully deleted 42 traces"
        }
      },
      "headers": {
        "Authorization": "Bearer YOUR_RESPAN_API_KEY"
      }
    },
    {
      "name": "Delete selected trace IDs",
      "query-parameters": {
        "start_time": "2025-01-01T00:00:00Z",
        "end_time": "2025-01-31T23:59:59Z",
        "environment": "prod"
      },
      "request": {
        "filters": {
          "trace_unique_id": {
            "operator": "in",
            "value": [
              "trace-01",
              "trace-02"
            ]
          }
        }
      },
      "response": {
        "body": {
          "success_count": 42,
          "error_count": 0,
          "errors": [],
          "deleted_count": 42,
          "message": "Successfully deleted 42 traces"
        }
      },
      "headers": {
        "Authorization": "Bearer YOUR_RESPAN_API_KEY"
      }
    }
  ]
}

OpenAPI path metadata

{}

Referenced OpenAPI components

{
  "schemas": {
    "BulkDeleteResponse": {
      "description": "Canonical bulk result envelope plus delete-specific fields.",
      "allOf": [
        {
          "$ref": "#/components/schemas/BulkOperationResponse"
        },
        {
          "type": "object",
          "required": [
            "deleted_count",
            "message"
          ],
          "properties": {
            "deleted_count": {
              "type": "integer",
              "minimum": 0,
              "description": "Number of resources matched and processed for deletion."
            },
            "message": {
              "type": "string",
              "description": "Human-readable deletion result."
            }
          }
        }
      ]
    },
    "BulkItemError": {
      "type": "object",
      "description": "An item that failed during a bulk operation. `index` is zero-based and identifies the corresponding item in the request array.",
      "required": [
        "index",
        "error"
      ],
      "properties": {
        "index": {
          "type": "integer",
          "minimum": 0,
          "description": "Zero-based index of the failed item in the submitted array."
        },
        "error": {
          "type": "string",
          "description": "Error message for the failed item."
        }
      }
    },
    "BulkOperationResponse": {
      "type": "object",
      "description": "Canonical result envelope for a bulk operation.",
      "required": [
        "success_count",
        "error_count",
        "errors"
      ],
      "properties": {
        "success_count": {
          "type": "integer",
          "minimum": 0,
          "description": "Number of items successfully processed."
        },
        "error_count": {
          "type": "integer",
          "minimum": 0,
          "description": "Number of items that failed."
        },
        "errors": {
          "type": "array",
          "description": "Item-level failures, keyed by zero-based input index.",
          "items": {
            "$ref": "#/components/schemas/BulkItemError"
          }
        }
      },
      "example": {
        "success_count": 1,
        "error_count": 0,
        "errors": []
      }
    },
    "TraceBulkDeleteFilters": {
      "type": "object",
      "description": "Required. Selects the traces to delete.\n\nEach key is a field to filter on, and each value is a condition: `{\"<field>\": {\"operator\": \"<operator>\", \"value\": [...]}}`. A trace must match every condition. To set two conditions on one field, such as a range, pass a list of conditions.\n\n**Operators:** `\"\"` (equals, the default), `not`, `in`, `not_in`, `lt`, `lte`, `gt`, `gte`, `contains`, `not_contains`, `icontains` (ignores case), `startswith`, `not_startswith`, `endswith`, `not_endswith`, `empty`, `not_empty`. Put values in a list: `\"\"` and `in` match any of the listed values, and `not` and `not_in` match none of them. Other operators take one value; for `empty` and `not_empty`, send `[\"\"]`.\n\n**Fields:** `trace_unique_id`, `customer_identifier`, `environment`, `start_time`, `end_time`, `span_count`, `llm_call_count`, `error_count`, `total_cost`, `total_prompt_tokens`, `total_completion_tokens`, `total_tokens`, and `metadata__<key>` (values are strings). Here `environment`, `start_time` and `end_time` only narrow the window set by the query parameters. Unsupported fields or operators return a 400 error, and nothing is deleted.\n\n**Example:**\n\n```json\n{\n  \"trace_unique_id\": {\"operator\": \"in\", \"value\": [\"trace-01\", \"trace-02\"]}\n}\n```",
      "minProperties": 1,
      "properties": {
        "trace_unique_id": {
          "$ref": "#/components/schemas/TraceFilterCondition"
        },
        "unique_organization_id": {
          "$ref": "#/components/schemas/TraceFilterCondition"
        },
        "environment": {
          "$ref": "#/components/schemas/TraceFilterCondition"
        },
        "start_time": {
          "$ref": "#/components/schemas/TraceFilterCondition"
        },
        "end_time": {
          "$ref": "#/components/schemas/TraceFilterCondition"
        },
        "span_count": {
          "$ref": "#/components/schemas/TraceFilterCondition"
        },
        "llm_call_count": {
          "$ref": "#/components/schemas/TraceFilterCondition"
        },
        "total_cost": {
          "$ref": "#/components/schemas/TraceFilterCondition"
        },
        "total_prompt_tokens": {
          "$ref": "#/components/schemas/TraceFilterCondition"
        },
        "total_completion_tokens": {
          "$ref": "#/components/schemas/TraceFilterCondition"
        },
        "total_tokens": {
          "$ref": "#/components/schemas/TraceFilterCondition"
        },
        "error_count": {
          "$ref": "#/components/schemas/TraceFilterCondition"
        },
        "customer_identifier": {
          "$ref": "#/components/schemas/TraceFilterCondition"
        }
      },
      "additionalProperties": {
        "$ref": "#/components/schemas/TraceFilterCondition"
      },
      "example": {
        "customer_identifier": {
          "operator": "",
          "value": [
            "customer-123"
          ]
        }
      }
    },
    "TraceFilterCondition": {
      "type": "object",
      "description": "A trace filter condition. Use `is` for an exact value or `in` for any value in a list.",
      "required": [
        "value"
      ],
      "properties": {
        "operator": {
          "type": "string",
          "description": "Comparison operator. If omitted or empty, exact matching is used.",
          "default": "",
          "enum": [
            "",
            "not",
            "in",
            "not_in",
            "lt",
            "lte",
            "gt",
            "gte",
            "contains",
            "not_contains",
            "icontains",
            "startswith",
            "not_startswith",
            "endswith",
            "not_endswith",
            "empty",
            "notEmpty",
            "not_empty",
            "isnull"
          ]
        },
        "value": {
          "type": "array",
          "minItems": 1,
          "description": "One or more values used by the comparison.",
          "items": {}
        }
      },
      "additionalProperties": false,
      "example": {
        "operator": "in",
        "value": [
          "trace-01",
          "trace-02"
        ]
      }
    }
  },
  "securitySchemes": {
    "DashboardJwt": {
      "type": "http",
      "scheme": "bearer",
      "bearerFormat": "Dashboard JWT",
      "description": "Use a dashboard JWT only for dashboard-authenticated endpoints. Respan API-key endpoints use the respanApiKey auth field instead.",
      "x-fern-bearer": {
        "name": "dashboardJwt",
        "env": "RESPAN_DASHBOARD_JWT"
      }
    },
    "RespanApiKey": {
      "type": "http",
      "scheme": "bearer",
      "bearerFormat": "Respan API key",
      "description": "Use your Respan API key for Respan API authentication. Enter only the Respan API key value; clients send Authorization: Bearer <RESPAN_API_KEY>. For /api/responses, provider credentials such as Perplexity, OpenAI, or Azure OpenAI go in Settings -> Providers or respan_params.credential_override in the request body, not in this authentication field.",
      "x-fern-bearer": {
        "name": "respanApiKey",
        "env": "RESPAN_API_KEY"
      }
    }
  }
}