API Reference

API Reference

POST /api/ingest

The single endpoint for sending events from your agents to agent-os. Both SDKs use this endpoint internally.

Authentication

Authorization: Bearer <api-key>

API keys are created in Settings > API Keys. See the API Keys guide.

Rate limit

200 requests per minute per API key.

Request body

{
  "event_type": "run_start",
  "sdk_run_id": "abc123",
  "payload": { ... },
  "agent_name": "my-agent",
  "occurred_at": "2026-04-02T10:00:00Z"
}

Field	Type	Required	Description
event_type	string	Yes	One of the supported event types
sdk_run_id	string	Yes	Unique run identifier (generated by SDK)
payload	object	Yes	Event-specific data
agent_name	string	No	Agent name (used for auto-registration)
occurred_at	string	No	ISO-8601 timestamp (defaults to server time)

Supported event types

Event type	Effect
run_start	Creates a new AgentRun record, auto-registers agent
step	Records a node/step execution event
tool_call	Records a tool invocation event
error	Records an error, sets run status to error
run_end	Marks run as success, captures tokens, cost, model
human_input_requested	Sets run status to waiting_for_input
human_input_received	Sets run status back to running

Status mapping

The run status is updated based on the event type:

Event type	Run status
run_start	running
run_end	success
error	error
human_input_requested	waiting_for_input
human_input_received	running

Example: run_start

{
  "event_type": "run_start",
  "sdk_run_id": "run_a1b2c3",
  "agent_name": "research-agent",
  "payload": {
    "framework": "langgraph",
    "input": { "query": "What is the weather in Zurich?" }
  }
}

Example: step

{
  "event_type": "step",
  "sdk_run_id": "run_a1b2c3",
  "payload": {
    "node_name": "search_web",
    "phase": "end",
    "duration_ms": 890,
    "output": { "results": ["..."] }
  }
}

Example: tool_call

{
  "event_type": "tool_call",
  "sdk_run_id": "run_a1b2c3",
  "payload": {
    "tool_name": "web_search",
    "phase": "end",
    "input_preview": "Zurich weather today",
    "output_preview": "12°C and cloudy",
    "duration_ms": 740
  }
}

Example: run_end

{
  "event_type": "run_end",
  "sdk_run_id": "run_a1b2c3",
  "payload": {
    "output": { "answer": "It is 12°C and cloudy." },
    "prompt_tokens": 150,
    "completion_tokens": 45,
    "total_tokens": 195,
    "cost_usd": 0.0023,
    "model": "gpt-4"
  }
}

Example: error

{
  "event_type": "error",
  "sdk_run_id": "run_a1b2c3",
  "payload": {
    "error_type": "ValueError",
    "error_message": "API rate limit exceeded",
    "traceback": "Traceback (most recent call last):\n  ..."
  }
}

Response

Success:

{
  "status": "ok",
  "event_id": 42
}

With budget warning:

{
  "status": "ok",
  "event_id": 42,
  "budget_warning": "Agent 'my-agent' has exceeded its budget of $10.00"
}

Side effects

When an event is ingested:

1. Persisted — AgentEvent record created in Postgres
2. Run updated — AgentRun status, tokens, and cost updated
3. Broadcast — Event pushed to WebSocket channel user.{userId} via Laravel Reverb
4. Alerts checked — Matching alert rules fire and dispatch notification jobs
5. Agent registered — On run_start, the agent is auto-created if it doesn’t exist