> ## Documentation Index
> Fetch the complete documentation index at: https://agentrail.co/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Alerts

> Find out when agents in your real traffic start one of your jobs and stop before finishing it, by email, in Slack and on the Alerts page.

Agents come to your product to get jobs done. **Alerts** tells you when they start one and stop before finishing it: which job, how far they got, where they stopped, what your product answered there, and which agents. It reads the [journeys](https://agentrail.co/docs/guides/journeys.md) recorded from your own traffic, so it needs at least one [journey source](https://agentrail.co/docs/guides/journeys.md#set-up-sources) sending events.

Every count is a count of journeys, each one agent's attempt. Only journeys made by agents count; journeys made by people, and by actors that could not be identified, never do.

## Jobs and where agents stop

A job is one of your [workflows](https://agentrail.co/docs/guides/workflows.md), and its steps are what an agent has to do. A journey is matched to a job by the requests, MCP tool calls and pages each step names, never by guesswork. A step that matches any request to a host, or any tool on an MCP server, never counts a journey in a job; only a step naming a specific endpoint, tool or page does.

A journey counts once it is over: once nothing new has arrived from it for your workspace's journey window, 24 hours unless you set another. While journey linking runs behind, alerts wait with it. Journeys whose last step is more than 30 days old are never counted.

* A journey **counts in** a job when one of its calls matches a step of that job and of no other job. If every call it matched is shared, it counts in the smallest job whose steps match them all. It also counts in every job it finished.
* It **finished** the job when it completed the last step and your product accepted it. Where you track the workflow on its **Production** tab, the tracked outcome decides instead.
* Otherwise it stopped at one place. If every answer it got at the last step it reached failed, your product **refused** it there. If that answer was a 401, it is **waiting on sign-in** there. If not, it **did not continue after** the last step it completed.

For example, an agent creates an API key, adds a domain, then calls `POST /emails` and gets 422: it was refused at "Send the email", where your product rejected it as invalid (422). An agent that creates a key, adds a domain and then leaves did not continue after "Add a sending domain". One that gets 401 at `POST /emails` and leaves is waiting on sign-in at "Send the email".

A failed step is one the journey shows as failed: an HTTP answer of 400 or above, or an MCP tool or call that answered with an error. MCP `GET`, `HEAD` and `DELETE` requests answered 405 are the protocol's normal answers, never a failed step. An MCP tool call whose result was not recorded is neither: a job whose last reached step got only such answers counts as neither finished nor stopped. One journey can count in several jobs: one that adds and verifies a domain and then sends an email counts in "Send a first email" and in "Verify a domain", finished in both.

### Sign-in is not a failure

An agent that stops at sign-in needs a person to approve it, which is correct. A 401, or a 401 followed only by reads of your sign-in metadata (`/.well-known/*`, `/auth.md`, `/openapi.json`) and more 401s on the same host, is sign-in. Sign-in never raises an alert. Inside a job it shows as **waiting on sign-in** on its own line, outside the job's count of stopped agents. Outside your jobs it is not counted at all. A 403 is different: your product refused access to an agent that was signed in, and it counts as a refusal.

### Outside your known jobs

A journey that counts in no job and ends on a failed step that is not sign-in is a stop **outside your known jobs**. These are grouped by the host of the failed call and your product's answer, such as **not found (404) on api.resend.com**, and the alert names the request the group's first journey failed on, such as **not found (404) on [www.resend.com](http://www.resend.com), first at GET /.well-known/oauth-authorization-server**. Open a group to see each journey's last failed request, such as `GET /domains/:id/records`, the latest first.

A journey that counts in no job and ends without a failure is not counted: nothing says what it was trying to do.

Scanners and probes that call themselves agents never raise alerts and never appear in a job or a group. The Alerts page shows only how many there were.

## The first alert

The first time agents stop at a place in your workspace, refused at a step of a job, not continuing after a step, or in a new group outside your known jobs, your workspace gets a first alert at the next alerts pass, which runs every 15 minutes:

* an email to every Admin of your organization who has alert emails on;
* a message in the Slack channel an Admin picked;
* the stop on the Alerts page, counted in the badge beside **Alerts** in the sidebar.

When one pass finds several new stops, one email and one Slack message list them all. For each stop the alert names the job and the step, what your product answered, its numbers so far, the agents that stopped beside the agents that finished the job, and the most recent journey's last steps, each said as the job's step where it matches one, with links to the journeys and the job.

A stop is first only once. Agents stopping there again, even after a quiet stretch, go into the daily summary, never a new first alert.

When alerts first look at your workspace, agents may already be stopping in places. Those stops get no first alert each: one email and one Slack message headed **Agents already stop at these steps** lists them, with each one's numbers over the last 30 days and its replay. Every stop after that gets a first alert.

### Why agents stop: the replay

Live traffic shows where an agent stopped and the answer it got, never what it read or was thinking. Each new stop in a job starts a replay when it can: a simulation that runs the job's scenarios with the same agent and the model its journey recorded. Each replay run starts where the job's scenarios start, not where the agent that stopped had got to. Replay runs count toward your scheduled simulation runs for that scenario and model in the period. When the replay's runs are judged, the stop shows where its agents stopped, the failure kind and the agent's own words, with links to the runs, on the Alerts page and as a reply in the first alert's Slack thread. When every replay run finished the job, the stop says it did not reproduce.

When no replay can run, the stop says why:

* **No job covers this stop**: the stop is outside your known jobs, so no job's scenarios exist;
* **This agent can't run in simulations yet**, such as a consumer chat assistant;
* **Model not recorded**: the journey didn't record which model the agent used.

No other agent or model stands in for the one that stopped.

## The daily summary

Every day at 10:00 a.m. Pacific time, moving with daylight saving, your workspace gets a summary of the journeys alerts counted in the last 24 hours, against the 24 hours before. It lists every job whose funnel changed, with agents waiting on sign-in on their own line, and every group outside your known jobs whose count changed. It goes by email to each Admin with alert emails on and as one message in the Slack channel. A day with no change sends nothing.

## The Alerts page

Open **Alerts** in the sidebar. Every member of the workspace sees it. Pick a period: **24 hours**, **7 days** or **30 days**, each against the period of the same length before it.

**Jobs** come first, those with the most stopped agents first; then **Outside known jobs**; then the count of scanners and probes. Each job shows its stopped agents per day over time, then its funnel: how many agents counted in it and finished it, and at each step how many were refused there, did not continue after it, or are waiting on sign-in there, each number beside its change against the previous period. Where agents were refused you see what your product answered, in plain words with the code beside it, with a count for each answer. A step your workflow no longer has keeps its title, marked **No longer in the job**.

Select a stop to see the agents that stopped there beside the agents that finished the job, each with its name and model, or **model not recorded**; how many journeys were proven and how many inferred; the most recent journey's last three steps; a link to every journey that stopped there, the latest first, with **Show more** for the rest; and the replay.

The badge counts new stops since you last opened the page, not counting sign-in. Opening the page clears it.

## Turn off alert emails

Alert emails go to every Admin of the organization. Each person can turn them off for themselves: open Settings, select the **Account** tab and turn off **Email me journey alerts**. Every alert email links there. Turning them off stops only your own emails; other Admins, the Slack channel and the Alerts page are unchanged.

## Send alerts to Slack

An Admin picks one Slack channel for alerts:

**1. Connect Slack**

In Settings, select the **Integrations** tab and connect Slack, if your workspace hasn't yet.

**2. Pick the channel**

Under Slack, in **Alerts channel**, choose the public channel and select **Save**. **Alerts channel** shows while Slack is connected. Agentrail can post there without being invited to it.

First alerts and daily summaries then go to that channel. To stop Slack messages, select **Clear** under **Alerts channel**. With no channel picked, or Slack not connected, no Slack message is sent; email and the Alerts page carry on as before.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.