Reference · 01

Monitoring & analytics.

See how a live agent is doing from your own code: daily totals of conversations or runs from the stats endpoint, the individual sessions and runs behind them, and a review by Alchemist that finds what is going wrong.

You want	Use
Volume, failures, handoffs and cost per day	`GET /api/agents/{agent_id}/stats`
The conversations behind the numbers	Session management
The runs behind the numbers, e.g. every failed run	Run management (`GET .../runs?status=failed`)
What is going wrong and how to fix it	Ask Alchemist for a review

Agent stats

GET /api/agents/{agent_id}/stats

Returns a live agent's totals for the last 1, 7 or 30 days, and one row per day. Chat agents and jobs each get their own fields. Only live traffic is counted; test conversations and test runs are left out. Authenticate with the same Access Key as triggers.

Query parameters

Name	Type	Default	Description
`days`	`integer`	`7`	The window: `1`, `7` or `30`. Days are UTC calendar days ending today, so `days=1` is today so far.

Any other query parameters are ignored.

Agent stats · cURLshell

curl "https://webhook.olbrain.com/api/agents/agt_01HAKZ.../stats?days=7" \
  -H "Authorization: Bearer ak_<your-access-key>"

Chat agent

Response shape · chat agentJSON

{
  "agent_id": "agt_01HAKZ...",
  "kind": "chat",
  "window_days": 7,
  "since": "2026-11-05T00:00:00Z",
  "totals": {
    "conversations": 5,
    "resolved": 2,
    "handed_off": 1,
    "messages": 23,
    "failed_replies": 1,
    "tokens": 9000,
    "cost_inr": 1.43
  },
  "days": [
    {
      "day": "2026-11-05",
      "conversations": 4,
      "resolved": 2,
      "handed_off": 1,
      "messages": 20,
      "failed_replies": 1,
      "tokens": 9000,
      "cost_inr": 1.23
    }
  ]
}

Field	Meaning
`conversations`	Conversations that started that day.
`resolved`	Of those, conversations that ended well: a real exchange that went quiet for 24 hours on a positive note. A conversation is judged only after it has been quiet for 24 hours, so the last day or two keep rising.
`handed_off`	Of those, conversations the agent handed to a person.
`messages`	Messages the agent answered.
`failed_replies`	Messages the agent failed to answer (the reply's `status` is `error`).
`tokens`	Model tokens used.
`cost_inr`	Usage at Olbrain's rates, in rupees, rounded to the paisa.

Job

Response shape · jobJSON

{
  "agent_id": "agt_01HB2Q...",
  "kind": "job",
  "window_days": 1,
  "since": "2026-11-11T00:00:00Z",
  "totals": {
    "runs_finished": 5,
    "runs_succeeded": 4,
    "runs_failed_or_cancelled": 1,
    "items_processed": 40,
    "items_failed": 2,
    "tokens": 1200,
    "cost_inr": 3
  },
  "days": [
    {
      "day": "2026-11-11",
      "runs_finished": 5,
      "runs_succeeded": 4,
      "runs_failed_or_cancelled": 1,
      "items_processed": 40,
      "items_failed": 2,
      "tokens": 1200,
      "cost_inr": 3
    }
  ]
}

Field	Meaning
`runs_finished`	Runs that finished that day, whatever the result. A run counts on the day it finishes.
`runs_succeeded`	Of those, runs that completed.
`runs_failed_or_cancelled`	Of those, runs that failed or were cancelled. Find them with `GET .../runs?status=failed`.
`items_processed`	Items that went through every step.
`items_failed`	Items that failed at a step. Fetch the run to see which step and why.
`tokens`	Model tokens used.
`cost_inr`	Usage at Olbrain's rates, in rupees, rounded to the paisa.

days always holds one row per day in the window, oldest first, with zeros on days without activity. Runs still going or waiting for an approval aren't counted until they finish; list them with GET .../runs?status=running or ?status=needs_review.

No push notifications yet

Olbrain doesn't call your server when a run fails. To be alerted, poll /stats or GET .../runs?status=failed on a schedule. For chat agents, Alchemist can set who is told when a conversation is handed to a person: an email address, a Slack channel or your helpdesk.

Errors

Status	Code	When
400	`invalid_days`	`days` is not `1`, `7` or `30`.
400	`runtime_not_applicable`	The agent is a research agent. Stats cover chat agents and jobs.
401	`unauthorized`	Missing or invalid Access Key.
404	`agent_not_found`	The agent doesn't exist or belongs to another organization.
500	`internal_error`	The stats couldn't be read. Retry with backoff.

For the full error reference, see Errors.

Ask Alchemist for a review

In Claude Code, Codex or any client with Alchemist, ask it to review a live agent, for example “How has the support agent done this week?” Alchemist reads the last 1, 7 or 30 days of live traffic, with customer details hidden:

Chat agents: how many conversations there were, cost per conversation, how often they went to a person, and groups of failures (failed replies, thumbs-down replies, tool failures and recurring problems) with example exchanges.
Jobs: how many runs there were and how many failed or needed review, with the failed runs grouped by the step they stopped at, with example errors.

For a chat agent it can then turn a failure into a test, fix the agent and show the test passing before the fix goes live. It reviews only when you ask.