Add Span

Add a span to an existing trace

POST /v1/traces/{trace_id}/spans

cURL

curl -X POST https://api.playgent.com/v1/traces/trace_ghi789/spans \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "parent_span_id": "span_jkl012",
    "name": "gpt-4-turbo call",
    "kind": "llm",
    "input": {
      "messages": [
        { "role": "system", "content": "You are a helpful assistant." },
        { "role": "user", "content": "What is your refund policy?" }
      ],
      "model": "gpt-4-turbo",
      "temperature": 0.7
    },
    "start_time": "2024-12-16T10:00:00.123Z"
  }'

Response

{
  "span_id": "span_mno345"
}

Add a span to capture a specific operation during agent execution (LLM call, tool invocation, retrieval, etc.).

trace_id · string · required

Parent trace identifier

parent_span_id · string

Parent span ID for nested spans

name · string · required

Span name (e.g., “gpt-4-turbo call”, “vector_search”)

kind · string · required

Span type: llm, tool, retrieval, agent, chain

input · object · required

Span input data

Show properties

messages · array

For LLM spans: input messages

model · string

For LLM spans: model name

temperature · number

For LLM spans: temperature setting

query · string

For retrieval spans: search query

tool_args · object

For tool spans: tool arguments

start_time · string · required

ISO 8601 timestamp when span started

span_id · string · required

Unique span identifier

cURL

curl -X POST https://api.playgent.com/v1/traces/trace_ghi789/spans \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "parent_span_id": "span_jkl012",
    "name": "gpt-4-turbo call",
    "kind": "llm",
    "input": {
      "messages": [
        { "role": "system", "content": "You are a helpful assistant." },
        { "role": "user", "content": "What is your refund policy?" }
      ],
      "model": "gpt-4-turbo",
      "temperature": 0.7
    },
    "start_time": "2024-12-16T10:00:00.123Z"
  }'

Response

{
  "span_id": "span_mno345"
}