Skip to main content
A Turn represents a single atomic interaction cycle: User Input -> Agent Processing -> Agent Output. Turns are immutable once recorded.

​
Create Turn

​
session_id
string
required
The ID of the session this turn belongs to.
​
input
object
required
The user’s input. Must contain type (e.g. “text”) and content.
​
output
object
required
The agent’s response. Must contain type and content.
​
metadata
object
Arbitrary metrics (token usage, latency, model versions).
​
reasoning
string
Optional internal monologue or “Check-of-Thought” trace from the agent.
curl -X POST https://api.statebase.org/v1/sessions/sess_123/turns \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "type": "text",
      "content": "What is the capital of France?"
    },
    "output": {
      "type": "text",
      "content": "The capital of France is Paris."
    },
    "metadata": {
      "model": "gpt-4",
      "tokens_input": 15,
      "tokens_output": 7
    },
    "reasoning": "User is asking a geography fact. Retrieving from general knowledge."
  }'

​
List Turns

Retrieve the conversation history for a session.
​
session_id
string
required
The session ID.
​
limit
integer
default:"20"
Max results to return.
​
order
string
default:"desc"
Sort order: asc or desc.
curl https://api.statebase.org/v1/sessions/sess_123/turns?limit=5 \
  -H "Authorization: Bearer <token>"