API Reference — AgentWatch

POST

/api/traces/session

Create or Upsert a Session

Register a tracing session before sending events. If a session with the given id already exists, its metadata is updated. Called automatically by the Python SDK's @agentwatch.track() decorator.

# Python — using the SDK's context manager (recommended)
import agentwatch as aw

# Configure once at app startup
aw.configure(api_base="https://agentwatch-3.polsia.app", api_key="your-api-key")

@aw.track(agent_name="my-agent", framework="openai")
def my_agent():
    # Your agent logic here — session is created automatically
    pass

# Or create session explicitly (for async workflows)
session = aw.start_session_async(
    agent_name="my-agent",
    framework="openai",
    metadata={"user_id": "123"}
)
# session.id is the session_id you pass to ingest
await session.end()

# curl — raw REST call (for non-Python environments)
curl -X POST https://agentwatch-3.polsia.app/api/traces/session \n
  -H "Content-Type: application/json" \n
  -H "X-API-Key: your-api-key" \n
  -d '{
    "id": "session-abc123",
    "agent_name": "my-agent",
    "framework": "openai",
    "started_at": "2026-06-08T12:00:00Z",
    "metadata": {"user_id": "123"},
    "max_cost_cents": 500
  }'

Field	Type		Description
id	string	required	Unique session identifier. Use a UUID or stable string that your agent can generate and reuse.
agent_name	string	required	Human-readable agent name, used for filtering and baseline grouping.
framework	string	required	Instrumented framework: `openai`, `crewai`, `langgraph`, `autogen`, `llamaindex`.
started_at	ISO 8601 string		Session start timestamp. Defaults to now if omitted.
metadata	object		Arbitrary key/value pairs to attach to the session (user_id, request_id, etc.).
max_cost_cents	integer		Session cost ceiling in cents. Exceeding it triggers a `cost_cap_exceeded` event and halts ingestion.

Response 200 OK

{
  "ok": true,
  "session": {
    "id": "session-abc123",
    "agent_name": "my-agent",
    "framework": "openai",
    "started_at": "2026-06-08T12:00:00Z",
    "status": "active",
    "max_cost_cents": 500
  }
}

POST

/api/traces/ingest

Ingest Trace Events

Send a batch of trace events (LLM calls, tool calls, context retrievals) for a running session. Events are processed sequentially and anomaly detection runs after insert. Cost is computed automatically for llm_call events using the model pricing matrix.

# The SDK calls this automatically — you don't need to call it directly.
# For manual instrumentation, import the client:
from agentwatch.client import TraceClient

client = TraceClient(
    api_base="https://agentwatch-3.polsia.app",
    api_key="your-api-key"
)

events = [
    {
        "type": "llm_call",
        "model": "gpt-4o",
        "prompt_tokens": 1200,
        "completion_tokens": 350,
        "duration_ms": 1200,
        "status": "success"
    },
    {
        "type": "tool_call",
        "tool_name": "web_search",
        "duration_ms": 450,
        "status": "success"
    }
]

result = client.ingest("session-abc123", events)
# result.halted — True if session cost cap was exceeded
print(result.count, "events ingested")

# curl — raw REST call
curl -X POST https://agentwatch-3.polsia.app/api/traces/ingest \n
  -H "Content-Type: application/json" \n
  -H "X-API-Key: your-api-key" \n
  -d '{
    "session_id": "session-abc123",
    "events": [
      {
        "type": "llm_call",
        "model": "gpt-4o",
        "prompt_tokens": 1200,
        "completion_tokens": 350,
        "duration_ms": 1200,
        "status": "success"
      },
      {
        "type": "tool_call",
        "tool_name": "web_search",
        "duration_ms": 450,
        "status": "success"
      }
    ]
  }'

Field	Type		Description
session_id	string	required	ID of the session to attach events to. Must be registered via `POST /traces/session` first.
events	array	required	Array of event objects. Each must have a `type`. Supported types: `llm_call`, `tool_call`, `context_retrieval`.

Response 200 OK

{
  "ok": true,
  "count": 2,
  "halted": false,
  "warnings": []
}

GET

/api/sessions/:id

Get Session with Events

Retrieve a session's metadata, all its events, and aggregate totals (LLM call count, tool call count, total cost) in one call. Use this to build a trace viewer or audit log.

# Python — using the SDK client
from agentwatch.client import TraceClient

client = TraceClient(
    api_base="https://agentwatch-3.polsia.app",
    api_key="your-api-key"
)

session_data = client.get_session("session-abc123")

print(session_data.session.agent_name)   # "my-agent"
print(session_data.totals.llm_call_count) # 12
print(session_data.totals.total_cost_usd) # 0.0042
# Iterate events for a trace viewer
for ev in session_data.events:
    print(ev.type, ev.model, ev.duration_ms)

# curl — raw REST call
curl https://agentwatch-3.polsia.app/api/sessions/session-abc123 \n
  -H "X-API-Key: your-api-key"

Response 200 OK

{
  "session": {
    "id": "session-abc123",
    "agent_name": "my-agent",
    "framework": "openai",
    "status": "completed",
    "started_at": "2026-06-08T12:00:00Z",
    "ended_at":   "2026-06-08T12:05:00Z",
    "total_cost_usd": 0.0042,
    "total_tokens":   1550,
    "metadata": { "user_id": "123" }
  },
  "events": [
    {
      "id": 42,
      "type": "llm_call",
      "model": "gpt-4o",
      "prompt_tokens": 1200,
      "completion_tokens": 350,
      "cost_usd": 0.00405,
      "duration_ms": 1200,
      "status": "success",
      "accumulated_cost_usd": 0.00405
    }
  ],
  "totals": {
    "llm_call_count": 12,
    "tool_call_count": 8,
    "context_retrieval_count": 3,
    "total_cost_usd": 0.0183,
    "total_tokens": 8420
  }
}

GET

POST

/api/alerts/rules

Get / Update Governance Rules

Query the current anomaly detection rule configuration or update it. Rules are evaluated against every batch of events during ingestion. The sigma threshold controls behavioral baseline deviation sensitivity.

# Python — get current rules
import requests

resp = requests.get(
    "https://agentwatch-3.polsia.app/api/alerts/rules",
    headers={"X-API-Key": "your-api-key"}
)
config = resp.json()
print(config["global_rules"])   # list of rule objects
print(config["sigma"])           # 2.0

# Python — update rules
new_rules = [
    {
        "name":        "Token Spike",
        "type":        "token_spike",
        "threshold":   10000,
        "severity":     "HIGH",
        "enabled":     True
    },
    {
        "name":        "Cost Ceiling",
        "type":        "cost_ceiling",
        "threshold":   5.0,
        "severity":     "MEDIUM",
        "enabled":     True
    }
]

resp = requests.post(
    "https://agentwatch-3.polsia.app/api/alerts/rules",
    headers={"X-API-Key": "your-api-key"},
    json={"global_rules": new_rules, "sigma": 2.5}
)
print(resp.json())

# GET current rules
curl https://agentwatch-3.polsia.app/api/alerts/rules \n
  -H "X-API-Key: your-api-key"

# POST update rules
curl -X POST https://agentwatch-3.polsia.app/api/alerts/rules \n
  -H "Content-Type: application/json" \n
  -H "X-API-Key: your-api-key" \n
  -d '{
    "global_rules": [
      {"name": "Token Spike",   "type": "token_spike",   "threshold": 10000, "severity": "HIGH",   "enabled": true},
      {"name": "Cost Ceiling",  "type": "cost_ceiling",  "threshold": 5.0,   "severity": "MEDIUM", "enabled": true}
    ],
    "sigma": 2.5
  }'

Field	Type		Description
global_rules	array	required	Array of rule objects. Each rule needs `name`, `type`, `threshold`, `severity`, and `enabled`. Types: `token_spike`, `cost_ceiling`, `tool_frequency`, `failed_llm`.
sigma	number		Standard deviation multiplier for behavioral baseline deviation alerts. Range: 0.5–5. Default: 2.

Response 200 OK

{
  "ok": true,
  "config": {
    "global_rules": [
      {
        "name": "Token Spike",
        "type": "token_spike",
        "threshold": 10000,
        "severity": "HIGH",
        "enabled": true
      }
    ],
    "sigma": 2.5
  }
}

Quick-StartEndpoints

Quick-Start
Endpoints