State

Get a complete snapshot of a session's emotional state, including all internal dynamics and prompt_data.

Get Session State

GET /v1/state/:sessionId

Returns the full emotional state of a session.

Path Parameters

Parameter	Type	Description
`sessionId`	`string`	The session ID to query

Response

Field	Type	Description
`emotion`	`object`	Current emotional state `{ V, A, D }`
`emotion_intensity`	`number`	Overall emotion intensity `[0, 1]`
`discrete_emotion`	`object`	`{ primary, secondary, intensity }` labels
`body_budget`	`number`	Psychological energy level `[0, 1]`
`soul_stage`	`object`	`{ id, name }` — current stage (1-15)
`need_state`	`object`	Psychological needs (autonomy, competence, relatedness)
`regulation`	`object`	Active regulation strategy and history
`affect_dynamics`	`object`	Emotional variability and instability metrics
`prompt_data`	`object`	LLM-ready structured prompts

Examples

curl

curl https://api.molroo.io/v1/state/ses_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"

JavaScript

const response = await fetch("https://api.molroo.io/v1/state/ses_abc123", {
  headers: { Authorization: "Bearer YOUR_API_KEY" },
});
 
const state = await response.json();
 
console.log(state.emotion);          // { V: 0.72, A: 0.58, D: 0.31 }
console.log(state.discrete_emotion); // { primary: "joy", intensity: "moderate" }
console.log(state.body_budget);      // 0.85
console.log(state.soul_stage);       // { id: 3, name: "Attentive" }
 
// Use prompt_data for your LLM
console.log(state.prompt_data.formatted.system_prompt);
console.log(state.prompt_data.formatted.context_block);

Python

import requests
 
response = requests.get(
    "https://api.molroo.io/v1/state/ses_abc123",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
)
 
state = response.json()
print(state["emotion"])          # {"V": 0.72, "A": 0.58, "D": 0.31}
print(state["discrete_emotion"]) # {"primary": "joy", "intensity": "moderate"}

Errors

Code	Status	Description
`UNAUTHORIZED`	401	Invalid or missing API key
`NOT_FOUND`	404	Session not found

State

On this page