> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gp.scale.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create trace deletion request



## OpenAPI

````yaml /openapi/v5.yaml post /v5/spans/deletions
openapi: 3.1.0
info:
  title: EGP API V5
  description: >-
    This is the parent API for all EGP APIs. If you are looking for the EGP API,
    please go to https://api.egp.scale.com/docs.
  contact:
    name: Scale Generative AI Platform
    url: https://scale.com/genai-platform
  version: 0.1.0
servers:
  - url: https://api.egp.scale.com
security: []
paths:
  /v5/spans/deletions:
    post:
      tags:
        - Spans
      summary: Create trace deletion request
      operationId: POST-V5-/v5/spans/deletions
      parameters:
        - name: x-selected-account-id
          in: header
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: Account ID Header
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TraceDeletionCreateRequest'
      responses:
        '202':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TraceDeletionCreateResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - APIKeyHeader: []
components:
  schemas:
    TraceDeletionCreateRequest:
      anyOf:
        - $ref: '#/components/schemas/TraceIdsDeletionCreateRequest'
        - $ref: '#/components/schemas/GroupDeletionCreateRequest'
      title: TraceDeletionCreateRequest
    TraceDeletionCreateResponse:
      properties:
        object:
          type: string
          title: Object
          default: trace_deletion
        deletion_request_id:
          type: string
          title: Deletion Request Id
        status:
          $ref: '#/components/schemas/TraceDeletionRequestStatus'
        trace_count:
          anyOf:
            - type: integer
            - type: 'null'
          title: Trace Count
        resolved_trace_count:
          anyOf:
            - type: integer
            - type: 'null'
          title: Resolved Trace Count
        tombstoned_span_count:
          anyOf:
            - type: integer
            - type: 'null'
          title: Tombstoned Span Count
          description: >-
            Live spans tombstoned in the tracing service, from the awaited
            propagation acknowledgement. Response-only (the durable record is
            sgp-traces' deletion audit). Null when propagation was skipped or
            ran best-effort. The tracing service applies its deletion cutoff per
            storage engine. On ClickHouse deployments this counts the identities
            live among the rows ingested at or before the cutoff and masks
            exactly those rows. On Postgres deployments an identity is one row
            whose ingested_at its latest write refreshed, so it counts
            identities whose latest write is at or before the cutoff: a span
            whose in-progress precursor was ingested before the cutoff and whose
            completion landed after it counts 1 on ClickHouse and 0 on Postgres.
            In this order both engines still serve the completion, so only the
            count differs; the reverse order, a lower-version write landing
            after the cutoff, also differs in read visibility. The cutoff is the
            deletion's arrival at the tracing service, so this is a race with an
            in-flight completion. On ClickHouse deployments a lower-version
            write of a span that lands after the cutoff is a second row: the
            deletion removes only the rows ingested at or before the cutoff and
            point reads then serve the surviving lower-version row. On Postgres
            deployments the upsert guard rejects a lower-version write while the
            row is live, so the one row keeps its pre-cutoff ingested_at, is
            masked, and no read serves the span. Both engines count the span
            once here. Only a write landing after the mask, when the masked row
            admits any version, behaves the same on both engines. On ClickHouse
            deployments a repeat deletion of traces an earlier audit already
            covers reports 0: its live count excludes every row ingested at or
            before the earlier audit's reach, whether or not that mask
            completed. On Postgres deployments the count is the rows still live
            at or before the cutoff, so a retry after a failed mask reports the
            rows it masks.
        soft_deleted_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Soft Deleted At
      type: object
      required:
        - deletion_request_id
        - status
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    TraceIdsDeletionCreateRequest:
      properties:
        reason_code:
          $ref: '#/components/schemas/TraceDeletionReasonCode'
        reason_details:
          anyOf:
            - type: string
              maxLength: 2000
            - type: 'null'
          title: Reason Details
          description: Optional bounded audit context for the deletion request.
        trace_ids:
          items:
            type: string
            maxLength: 256
            minLength: 1
          type: array
          title: Trace Ids
          description: Explicit trace IDs to delete. Limited to 10,000 after deduplication.
        group_id:
          type: 'null'
          title: Group Id
      type: object
      required:
        - reason_code
        - trace_ids
      title: TraceIdsDeletionCreateRequest
    GroupDeletionCreateRequest:
      properties:
        reason_code:
          $ref: '#/components/schemas/TraceDeletionReasonCode'
        reason_details:
          anyOf:
            - type: string
              maxLength: 2000
            - type: 'null'
          title: Reason Details
          description: Optional bounded audit context for the deletion request.
        trace_ids:
          type: 'null'
          title: Trace Ids
        group_id:
          type: string
          maxLength: 128
          minLength: 1
          title: Group Id
          description: Delete all traces in this group. Group deletions are uncapped.
      type: object
      required:
        - reason_code
        - group_id
      title: GroupDeletionCreateRequest
    TraceDeletionRequestStatus:
      type: string
      enum:
        - accepted
        - resolving
        - deleting
        - completed
        - failed
        - canceled
      title: TraceDeletionRequestStatus
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
          additionalProperties: true
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
    TraceDeletionReasonCode:
      type: string
      enum:
        - customer_requested_deletion
      title: TraceDeletionReasonCode
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: x-api-key

````