Turns API

Turns represent individual conversation exchanges between a user and your agent. Each turn captures the complete interaction context including input, output, state changes, and reasoning.

Why Log Turns?

Turns provide:

Complete audit trail of all agent decisions
Debugging capability (replay exact conversations)
Analytics (measure success rates, latency, tool usage)
Rollback points (revert to any previous turn)

Add Turn

POST /v1/sessions/{session_id}/turns Logs a new conversation turn. This is typically called after your agent generates a response.

Path Parameters

Parameter	Type	Required	Description
`session_id`	string	✅ Yes	Session ID to add turn to

Request Body

Field	Type	Required	Description
`input`	object	✅ Yes	User’s input (see Input Object below)
`output`	object	✅ Yes	Agent’s response (see Output Object below)
`reasoning`	string	No	Why the agent made this decision (for debugging)
`metadata`	object	No	Custom data (e.g., `{"tool_used": "weather_api", "latency_ms": 450}`)
`state_before`	object	No	Session state before this turn
`state_after`	object	No	Session state after this turn

Input Object

Field	Type	Required	Description
`type`	string	✅ Yes	Content type: `"text"`, `"audio"`, `"image"`, `"tool_call"`
`content`	string	✅ Yes	The actual input content

Output Object

Field	Type	Required	Description
`type`	string	✅ Yes	Content type: `"text"`, `"audio"`, `"image"`, `"tool_result"`, `"error"`
`content`	string	✅ Yes	The actual output content

Response

Field	Type	Description
`id`	string	Unique turn ID (format: `turn_<12_chars>`)
`session_id`	string	Parent session ID
`turn_number`	integer	Sequential turn number (starts at 1)
`created_at`	string	ISO 8601 timestamp
`input`	object	User input
`output`	object	Agent output
`reasoning`	string	Agent’s reasoning (if provided)
`metadata`	object	Custom metadata
`state_before`	object	State snapshot before turn
`state_after`	object	State snapshot after turn

Example

curl -X POST https://api.statebase.org/v1/sessions/sess_abc123/turns \
  -H "X-API-Key: sb_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "type": "text",
      "content": "What is the weather in San Francisco?"
    },
    "output": {
      "type": "text",
      "content": "The weather in San Francisco is currently 72°F and sunny."
    },
    "reasoning": "Called weather API for San Francisco, returned current conditions",
    "metadata": {
      "tool_used": "weather_api",
      "latency_ms": 450,
      "model": "gpt-4"
    }
  }'

Get Turn

GET /v1/sessions/{session_id}/turns/{turn_id} Retrieves a specific turn by ID.

Path Parameters

Parameter	Type	Required	Description
`session_id`	string	✅ Yes	Session ID
`turn_id`	string	✅ Yes	Turn ID

Example

curl https://api.statebase.org/v1/sessions/sess_abc123/turns/turn_xyz789 \
  -H "X-API-Key: sb_your_key"

List Turns

GET /v1/sessions/{session_id}/turns Lists all turns for a session, ordered by creation time (newest first).

Path Parameters

Parameter	Type	Required	Description
`session_id`	string	✅ Yes	Session ID

Query Parameters

Parameter	Type	Required	Description
`limit`	integer	No	Max turns to return (default: 20, max: 100)
`starting_after`	string	No	Turn ID to start after (for pagination)
`order`	string	No	Sort order: `"asc"` or `"desc"` (default: `"desc"`)

Example

curl "https://api.statebase.org/v1/sessions/sess_abc123/turns?limit=10" \
  -H "X-API-Key: sb_your_key"

Common Use Cases

1. Logging Tool Calls

Track when your agent uses external tools:

# Agent calls weather API
weather_data = call_weather_api("San Francisco")

# Log the tool call
sb.sessions.add_turn(
    session_id=session.id,
    input={"type": "tool_call", "content": "get_weather(city='San Francisco')"},
    output={"type": "tool_result", "content": json.dumps(weather_data)},
    reasoning="Weather API call succeeded",
    metadata={
        "tool_name": "weather_api",
        "latency_ms": 450,
        "success": True
    }
)

2. Logging Errors

Track when things go wrong:

try:
    result = risky_operation()
except Exception as e:
    # Log the error
    sb.sessions.add_turn(
        session_id=session.id,
        input={"type": "text", "content": user_message},
        output={"type": "error", "content": str(e)},
        reasoning=f"Operation failed: {type(e).__name__}",
        metadata={
            "error_type": type(e).__name__,
            "error_message": str(e),
            "stack_trace": traceback.format_exc()
        }
    )

3. State Tracking

Log state changes with each turn:

# Before agent processes input
state_before = sb.sessions.get(session.id).state

# Agent processes and updates state
response = agent.process(user_message)
sb.sessions.update_state(session.id, new_state)

# Log turn with state snapshots
sb.sessions.add_turn(
    session_id=session.id,
    input={"type": "text", "content": user_message},
    output={"type": "text", "content": response},
    state_before=state_before,
    state_after=new_state,
    reasoning="Updated state based on user input"
)

4. Analytics

Analyze agent performance:

# Get all turns for a session
turns = sb.sessions.list_turns(session_id=session.id, limit=100)

# Calculate metrics
total_turns = len(turns)
tool_calls = [t for t in turns if t.metadata.get("tool_used")]
errors = [t for t in turns if t.output.type == "error"]
avg_latency = sum(t.metadata.get("latency_ms", 0) for t in turns) / total_turns

print(f"Total turns: {total_turns}")
print(f"Tool calls: {len(tool_calls)}")
print(f"Errors: {len(errors)}")
print(f"Avg latency: {avg_latency:.0f}ms")

Best Practices

✅ Do This

Always include reasoning (invaluable for debugging)
Log metadata (tool names, latency, model used, etc.)
Log errors (don’t just catch and ignore)
Use structured types ("text", "tool_call", "error")
Include state snapshots for critical turns

❌ Avoid This

Don’t skip turn logging (you’ll regret it when debugging)
Don’t log sensitive data in content (use encrypted metadata)
Don’t log every internal step (only user-facing interactions)
Don’t forget to paginate when listing turns

Turn Types Reference

Input Types

Type	Description	Example
`text`	Plain text input	`"What's the weather?"`
`audio`	Audio transcription	`"[Audio: 5.2s]"`
`image`	Image description	`"[Image: screenshot.png]"`
`tool_call`	Tool invocation	`"get_weather(city='SF')"`

Output Types

Type	Description	Example
`text`	Plain text response	`"It's 72°F and sunny"`
`audio`	Audio response	`"[Audio: response.mp3]"`
`image`	Generated image	`"[Image: chart.png]"`
`tool_result`	Tool output	`{"temp": 72, "condition": "sunny"}`
`error`	Error message	`"API timeout after 5s"`

Error Responses

Status Code	Error Code	Description
400	`invalid_request`	Missing required fields
404	`session_not_found`	Session doesn’t exist
404	`turn_not_found`	Turn doesn’t exist
429	`rate_limit_exceeded`	Too many requests

Next Steps

Sessions API: Manage session lifecycle
Memory API: Store long-term knowledge
Traces API: Audit and debugging

Key Takeaway: Turns are your time machine. Log everything, and you can replay any conversation to debug production issues.

Documentation Index

​Turns API

​Why Log Turns?

​Add Turn

​Path Parameters

​Request Body

​Input Object

​Output Object

​Response

​Example

​Get Turn

​Path Parameters

​Example

​List Turns

​Path Parameters

​Query Parameters

​Example

​Common Use Cases

​1. Logging Tool Calls

​2. Logging Errors

​3. State Tracking

​4. Analytics

​Best Practices

​✅ Do This

​❌ Avoid This

​Turn Types Reference

​Input Types

​Output Types

​Error Responses

​Next Steps

Turns API

Why Log Turns?

Add Turn

Path Parameters

Request Body

Input Object

Output Object

Response

Example

Get Turn

Path Parameters

Example

List Turns

Path Parameters

Query Parameters

Example

Common Use Cases

1. Logging Tool Calls

2. Logging Errors

3. State Tracking

4. Analytics

Best Practices

✅ Do This

❌ Avoid This

Turn Types Reference

Input Types

Output Types

Error Responses

Next Steps