Skip to main content
POST
/
api
/
public
/
v2
/
dataset-versions
/
add-trace
curl --request POST \
  --url https://api.promptlayer.com/api/public/v2/dataset-versions/add-trace \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data '
{
  "dataset_group_id": 123,
  "trace_id": "abc123def456"
}
'
{
  "success": true,
  "draft_dataset_id": 789,
  "mode": "trace"
}

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 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).

Authorizations

​
X-API-KEY
string
header
required

Body

application/json
​
dataset_group_id
integer
required

ID of the dataset group to add the trace row to.

Required range: x >= 1
​
trace_id
string
required

ID of the trace to add as a dataset row.

Minimum string length: 1
​
span_id
string | null

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).

Minimum string length: 1

Response

Trace added to draft dataset.

​
success
enum<boolean>
Available options:
true
​
draft_dataset_id
integer

ID of the draft dataset the trace row was added to.

​
mode
enum<string>

Indicates whether the row was created from a full trace root (trace) or a specific span subtree (span).

Available options:
trace,
span