> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aiaxoniq.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Incidents
> How aiAxonIQ opens an incident from a firing alert rule or a failing synthetic check, and how to acknowledge, assign and resolve it.
An incident is the operational record of one problem: when it was first seen,
how often it recurred, who acknowledged it, who it is assigned to, and when and
how it ended. It lives under **Govern → Incidents**.
Alerts answer *"is this condition true?"*. Incidents answer *"is somebody
handling it, and how long did that take?"* — the question two engineers woken by
the same page actually need answered.
**Reading incidents needs any role. Acknowledging, assigning and resolving
need the Editor role or higher.** Auditor and Viewer can read the list, the
detail page and the timeline, and the action buttons are shown disabled with
the reason. See [Roles and permissions](/concepts/roles).
## How an incident is created
You do not create incidents by hand — there is no "new incident" action. Three
producers open them:
| Source | Opens when | Closes when |
| :--------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------ |
| **Alert rule** | A rule moves from not firing to firing. | Automatically, when the rule's condition clears — or by hand. |
| **Synthetic check** | A synthetic check starts failing. One incident per rule and check. | **Only by hand.** |
| **Security detection** | A correlated security detection fires. These come from the SIEM section, which is **not generally available yet**, so most organizations will not see this source. One incident per detection group, not per detection window. | **Only by hand.** |
**Synthetic and security incidents never resolve themselves.** Only alert-rule
incidents close automatically when the condition clears. A synthetic check
that recovers leaves its incident open until someone resolves it — so an open
synthetic incident means "nobody has closed this yet", not necessarily "still
failing". Check the synthetic check itself before assuming it is still down.
### One problem, one incident
Each producer builds a deterministic key for the problem — for an alert rule,
the rule itself. While an incident for that key is open or acknowledged, a
repeat occurrence does **not** open a second incident. It updates the existing
one instead: *Last seen* moves forward, the occurrence counter goes up, and the
severity and title follow the newest occurrence, so a problem that gets worse
shows as worse.
Once an incident is resolved its key is released. The next time the same rule
fires, a **new** incident opens with its own timings. A resolved incident is
never reopened — otherwise a fix followed by a fresh failure a week later would
read as one incident that took a week to resolve.
**The incident is opened before the notification is sent.** A page that
arrives always refers to an incident you can already find. If the incident
cannot be recorded for some reason, the notification is still sent — a
bookkeeping failure never stops a page.
## Lifecycle
An incident has three states:
| State | Meaning |
| :------------- | :---------------------------------------------------------------------------------------------- |
| `OPEN` | The problem was detected and nobody has taken it yet. |
| `ACKNOWLEDGED` | A person has said "I am handling this". |
| `RESOLVED` | The problem is over — either the system saw it clear (`auto`) or a person closed it (`manual`). |
Three actions change an incident, from the buttons at the top of its detail
page:
Moves the incident from `OPEN` to `ACKNOWLEDGED` and records **you** as the
person who acknowledged it. Acknowledging stops escalation (see
[Escalation policies](/guides/alerts/escalation-policies)).
Acknowledging is idempotent: acknowledging an already-acknowledged incident
changes nothing, so a second click cannot move the recorded
acknowledgement time. The button is disabled once an incident is
acknowledged.
Gives the incident to a member of your organization. You can reassign at
any time until it is resolved. The assignee must be a member of this
organization; anything else is refused.
**Assignment is not acknowledgement.** Assigning an incident to someone who
is asleep says who *should* look at it, not that anybody has — so an
assigned but unacknowledged incident keeps escalating.
Closes the incident, recorded as a **manual** resolution attributed to you.
You are asked to confirm, because it cannot be undone: there is no reopen,
and a later recurrence becomes a new incident.
The person recorded against each action is always the signed-in user who
performed it. It is taken from your session, never from anything a client
sends.
## Timeline
Every incident has a timeline, oldest first, of what people and the system did
about it:
| Event | Recorded when |
| :--------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Incident opened** | The incident was created. Carries the evaluation detail — for an alert rule, the query, value, condition and threshold. |
| **Problem seen again** | A repeat occurrence of the same problem, with the occurrence count. |
| **Acknowledged** / **Assigned** / **Resolved** | A state change, with who did it. A resolution with no person attached was automatic. |
| **Escalated** | An escalation policy moved the incident up a level, with the level number. |
| **Notification withheld** | A notification for this incident was deliberately not sent — by a maintenance window or the notification rate limit — with which mechanism withheld it and on which channel. One entry per channel. |
A state change and its timeline entry are written together, so the timeline
cannot disagree with the incident's current state.
**"Notification withheld" entries appear on alert-rule incidents only.**
Notifications withheld for synthetic or security incidents are still
recorded as withheld, but not on the incident timeline.
## Time to acknowledge and time to resolve
The detail page shows **Time to acknowledge** (MTTA) and **Time to resolve**
(MTTR) for each incident, both measured from **first seen**:
* Time to acknowledge is first seen → the *first* acknowledgement.
* Time to resolve is first seen → resolution. The **Resolution** field tells you
whether that was `auto` (the system saw the condition clear) or `manual`
(somebody closed it), which is the distinction that makes an MTTR figure
meaningful.
Both values are computed from the timestamps on every read and are never
stored, so they cannot drift from the times shown beside them.
**There is no account-wide MTTA/MTTR report.** The figures are per incident.
The counters at the top of the Incidents page — Open, Acknowledged,
Unassigned, Resolved — are counted over the incidents the page loaded under
your current filters, and the page says so. They are not account-wide totals.
## Finding incidents
The Incidents page lists incidents with the most recent activity first. You can
filter by status, severity, source, assignee and time window (last 24 hours,
last 7 days — the default — last 30 days, or any time). The time window applies
to *Last seen*, so a long-running incident that is still recurring stays in a
short window.
One request returns at most 500 incidents. When a list comes back at that
ceiling the page warns that it may be incomplete — narrow the window or the
filters until the warning goes away.
The same data is available through the API; see the
[API reference](/api-reference/introduction).
## Incidents and the AI assistant
When an **alert rule** opens a **new** incident, aiAxonIQ can start one
automatic AI investigation for it, where the AI agent is enabled for your
deployment. At most one automatic investigation is ever started per incident —
a repeat occurrence does not start another — and it runs under the same limits
and admission ceilings as an investigation you start yourself. If the AI
service is unavailable or your account is at its investigation limit, the
incident and its notifications are unaffected; the investigation is simply not
started.
The Incidents page does not currently link to that automatic investigation.
To dig into an incident, open **AI Assistant → Investigate** and ask about it
directly; evidence an investigation cites can link back to the incident. See
[AI assistant](/guides/ai/assistant).
## Verify it works
Create or pick a threshold rule you can trip safely and use its **Test**
action first to confirm the channel works (see
[Alerting](/guides/alerts/overview)). Then let the real condition breach.
Within about a minute of the rule firing — the alert loop runs every 60
seconds — an incident with the rule's name appears under **Incidents** with
status `OPEN` and source **Alert rule**.
Open it and press **Acknowledge**. The status changes to `ACKNOWLEDGED`, the
timeline gains an *Acknowledged* entry naming you, and **Time to
acknowledge** appears.
When the condition stops breaching, the incident resolves on its own with
resolution `auto` and no person attached.
The **Test** action on a rule does **not** open an incident. Test
notifications are marked `[TEST]` and never merge with or resolve a real
incident.
## Troubleshooting
* **The rule was silenced.** A silence stops the rule from firing at all, so
no incident opens and no history is written. Check **Alerts →
Silences**. (A *maintenance window* is different: the incident still
opens and only the page is withheld.)
* **The rule is in cooldown.** After a rule fires it does not fire again
until its cooldown (default 5 minutes) has elapsed.
* **The rule is already firing.** An incident opens only on the transition
into firing. A rule that stays in breach updates its existing incident
rather than opening new ones.
* **The time window hides it.** The list defaults to the last 7 days of
activity; set the window to **Any time**.
Hover the button for the reason. Either your role is below Editor, the
incident is already resolved, or (for Acknowledge only) it is already
acknowledged.
The incident was already resolved — by a colleague, or automatically because
the condition cleared. Refresh the page to see its current state.
The person you chose is not a member of this organization, or the incident
no longer exists in it. The two cases are deliberately answered the same
way. Invite the person first, then assign.
It does not exist, or it belongs to another organization. The API answers
both the same way on purpose, so the page cannot tell you which. Check you
are signed in to the right organization.
Expected: only alert-rule incidents resolve automatically. Resolve it by
hand once you have confirmed the problem is over.
## Next
Page the next person when nobody acknowledges.
Stop a noisy rule, or hold pages during planned work.
Investigate an incident with the assistant.
Where incident notifications are delivered.