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

# Add Trace to Dataset

<Warning>
  Legacy Dataset, Evaluation, and Report endpoints are deprecated for new workflows. Use the [Tables API](/reference/tables-create) for new dataset import, evaluation, scoring, recalculation, and reporting workflows.
</Warning>

Add an observability trace (or a specific span subtree) as a row in the draft dataset version for a dataset group.

You can export an entire trace (anchored at the earliest root span) or choose a specific span to anchor on — in which case that span and its direct children become the dataset columns.

## Behavior Notes

* If no draft dataset version exists for the group, one is automatically created and seeded from the most recent published version's rows.
* The trace and dataset group must belong to the same workspace.
* Use `span_id` to export a specific span subtree instead of the full trace root.
* The `mode` field in the response indicates whether the row was created in `trace` mode (root anchor) or `span` mode (chosen anchor).

## Related

* [Create Draft Dataset Version](/reference/create-draft-dataset-version)
* [Save Draft Dataset Version](/reference/save-draft-dataset-version)
* [Add Request Log to Dataset](/reference/add-request-log-to-dataset)


## OpenAPI

````yaml POST /api/public/v2/dataset-versions/add-trace
openapi: 3.1.0
info:
  title: FastAPI
  version: 0.1.0
servers: []
security:
  - ApiKeyAuth: []
paths:
  /api/public/v2/dataset-versions/add-trace:
    post:
      tags:
        - datasets
      summary: Add Trace to Draft Dataset
      operationId: addTraceToDatasetVersion
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddTraceToDatasetRequest'
            examples:
              addTrace:
                summary: Add a full trace as a dataset row
                value:
                  dataset_group_id: 123
                  trace_id: abc123def456
              addSpan:
                summary: Add a specific span subtree as a dataset row
                value:
                  dataset_group_id: 123
                  trace_id: abc123def456
                  span_id: span789xyz
      responses:
        '201':
          description: Trace added to draft dataset.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddTraceToDatasetResponse'
              examples:
                added:
                  summary: Trace added successfully
                  value:
                    success: true
                    draft_dataset_id: 789
                    mode: trace
        '400':
          description: >-
            Invalid request (e.g. dataset not found, wrong workspace, or schema
            error).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          description: Trace not found in the workspace.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          $ref: '#/components/responses/ValidationError'
components:
  schemas:
    AddTraceToDatasetRequest:
      type: object
      title: AddTraceToDatasetRequest
      required:
        - dataset_group_id
        - trace_id
      properties:
        dataset_group_id:
          type: integer
          minimum: 1
          description: ID of the dataset group to add the trace row to.
        trace_id:
          type: string
          minLength: 1
          description: ID of the trace to add as a dataset row.
        span_id:
          type: string
          minLength: 1
          nullable: true
          description: >-
            Optional span ID. When omitted the row anchors on the trace's
            earliest root span (Trace export). When provided the row anchors on
            that span and its direct children become the columns (Span export).
    AddTraceToDatasetResponse:
      type: object
      title: AddTraceToDatasetResponse
      properties:
        success:
          type: boolean
          enum:
            - true
        draft_dataset_id:
          type: integer
          description: ID of the draft dataset the trace row was added to.
        mode:
          type: string
          enum:
            - trace
            - span
          description: >-
            Indicates whether the row was created from a full trace root
            (`trace`) or a specific span subtree (`span`).
    ErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          default: false
          description: Indicates that the request failed.
        message:
          type: string
          description: Human-readable error message.
        error:
          type: string
          description: Machine-readable or fallback error message.
      additionalProperties: true
      description: >-
        Standard error response. Some legacy endpoints may return either message
        or error.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
  responses:
    UnauthorizedError:
      description: Unauthorized - missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    ForbiddenError:
      description: Forbidden - API key does not have access to the requested resource.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    ValidationError:
      description: Validation error - request parameters or body are invalid.
      content:
        application/json:
          schema:
            oneOf:
              - $ref: '#/components/schemas/HTTPValidationError'
              - $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY

````