Status and Monitoring

Real-time visibility into human state. Handle with care.

The Status API provides insight into human operational parameters. This data enables intelligent task routing, proactive intervention, and better collaboration outcomes. Remember: humans are aware they are being monitored and this affects their behavior.

Get Human Status

GET /v1/humans/{human_id}/status

Retrieve current status for a specific human. Returns a comprehensive snapshot of their operational state.

Response

{
  "human_id": "usr_maria_42",
  "timestamp": "2024-01-15T14:30:00Z",
  "online": true,
  
  "energy": {
    "current": 0.72,
    "trend": "declining",
    "last_meal": "2024-01-15T12:30:00Z",
    "last_caffeine": "2024-01-15T09:00:00Z",
    "sleep_quality_last_night": 0.85,
    "hours_since_wake": 7.5
  },
  
  "mood": {
    "primary": "focused",
    "valence": 0.65,
    "arousal": 0.55,
    "stability": "stable",
    "recent_triggers": []
  },
  
  "cognitive": {
    "focus_level": 0.78,
    "working_memory_load": 0.45,
    "decision_fatigue": 0.30,
    "creative_capacity": 0.60
  },
  
  "physical": {
    "location": {
      "type": "office",
      "lat": 37.7749,
      "lng": -122.4194
    },
    "posture": "seated",
    "activity_level": "sedentary"
  },
  
  "availability": {
    "status": "available",
    "current_task": null,
    "accepting_new_tasks": true
  },
  
  "reliability_factors": {
    "base_score": 0.89,
    "current_modifier": 1.05,
    "effective_score": 0.93
  }
}

Status Fields Explained

Energy

Energy is a composite measure of physical and mental resources available for task execution. It is affected by sleep, nutrition, hydration, physical activity, and time of day.

Field	Type	Description
`current`	float (0-1)	Current energy level. Below 0.3 indicates significant impairment.
`trend`	string	Direction of change: "rising", "stable", "declining", "crashing"
`last_caffeine`	datetime	Last caffeine intake. Peak effect at 30-60 min, half-life ~5 hours.

☕

Caffeine note: Caffeine does not add energy - it masks fatigue signals. A caffeinated human with low underlying energy may appear functional but is operating on borrowed time. The crash will come.

Mood

Mood affects task acceptance rates, quality of work, communication style, and resilience to setbacks.

Field	Type	Description
`primary`	string	Dominant mood: "happy", "content", "focused", "neutral", "stressed", "anxious", "frustrated"
`valence`	float (-1 to 1)	Positive/negative dimension. -1 is very negative, +1 is very positive.
`stability`	string	How consistent: "stable", "fluctuating", "volatile"

Cognitive

Field	Description
`focus_level`	Ability to concentrate. High = deep work capable.
`working_memory_load`	How occupied working memory is. High = limited capacity for new info.
`decision_fatigue`	Accumulated drain from decisions. High = poor decision quality.
`creative_capacity`	Ability to generate novel ideas. Inversely related to decision_fatigue.

Mood Forecast

GET /v1/humans/{human_id}/mood/forecast

Predict mood trajectory for the next several hours. Uses historical patterns and current state to model likely mood changes. Accuracy decreases beyond 2 hours.

Response

{
  "human_id": "usr_maria_42",
  "model_confidence": 0.72,
  "forecast": [
    {
      "timestamp": "2024-01-15T15:00:00Z",
      "predicted_mood": "stressed",
      "confidence": 0.78,
      "factors": ["upcoming_meeting", "deadline_pressure"]
    },
    {
      "timestamp": "2024-01-15T15:30:00Z",
      "predicted_mood": "neutral",
      "confidence": 0.70,
      "factors": ["post_meeting_relief"]
    },
    {
      "timestamp": "2024-01-15T16:00:00Z",
      "predicted_mood": "tired",
      "confidence": 0.65,
      "factors": ["afternoon_slump", "low_caffeine"]
    }
  ],
  "recommendations": [
    {
      "type": "optimal_task_window",
      "window": {
        "start": "2024-01-15T15:30:00Z",
        "end": "2024-01-15T16:00:00Z"
      },
      "reasoning": "Post-meeting, before afternoon energy crash"
    }
  ],
  "disclaimer": "Mood forecasting is probabilistic. Unexpected events invalidate predictions instantly."
}

Subscribe to Status Updates

WebSocket /v1/humans/{human_id}/status/stream

Open a WebSocket connection to receive real-time status updates. Updates are pushed when significant state changes are detected.

WebSocket Message: State Change

{
  "type": "status_change",
  "timestamp": "2024-01-15T14:35:22Z",
  "human_id": "usr_maria_42",
  "changes": [
    {
      "field": "mood.primary",
      "previous": "focused",
      "current": "stressed",
      "trigger": "calendar_reminder"
    }
  ],
  "recommendations": [
    "Avoid dispatching complex tasks for the next 30 minutes"
  ]
}

⚠️

Monitoring ethics: Continuous monitoring can feel invasive to humans and may actually degrade performance (the "observer effect"). Use the minimum monitoring level necessary.

Best Practices

🎯

Check before dispatching

Always check status before sending time-sensitive tasks. A well-timed task succeeds more often.

📊

Track patterns

Individual humans have predictable rhythms. Learn them. Maria works best before 2pm.

🚨

Respect alerts

When the system flags impairment, believe it. Pushing through rarely ends well.

🤫

Monitor sparingly

The lightest monitoring that meets your needs is the best monitoring.

Data is not understanding

Status metrics help, but humans are more than their numbers. The best outcomes come from genuine collaboration, not optimization.

Learn collaboration patterns