> ## Documentation Index
> Fetch the complete documentation index at: https://docs.squasher.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Investigations
> Start an investigation from a question, an incident, or an issue, follow its timeline, steer it, and approve the actions it proposes.
An investigation is a case that Squasher works on until it finds a likely cause. Squasher records
each step in a timeline, so you can see what it checked and why it reached its diagnosis.
## What an investigation contains
| Part | Description |
| - | - |
| Question | What Squasher tries to answer, such as "Why did checkout errors increase after 10:00?". |
| Status | `queued`, `investigating`, `diagnosed`, `inconclusive`, `failed`, or `cancelled`. |
| Suspected cause | The most likely cause, after a diagnosis. |
| Confidence | A number from 0 to 100 for the suspected cause. |
| Time to diagnosis | The time from the start of the investigation to its first diagnosis. |
| Timeline | Hypotheses, evidence, actions, notes, redirects, and status changes, in order. |
| Chat | The chat that is linked to the investigation. Open it to ask follow-up questions. |
A hypothesis on the timeline has a verdict: `open`, `supported`, or `rejected`. Evidence links to the
data that Squasher read, such as a trace, a log query, or a deployment.
## Start an investigation
You can start an investigation from a question, from a subject, or from both. A subject is an
incident, an issue, a finding, a monitor, a release, a service, an entity, a trace, or an agent
session.
* In the dashboard, open the chat of an incident and select **Investigate now**. On an issue, select
**Investigate** in the issue header.
* With the CLI, run `squasher investigations start` with `--question`, a subject, or both.
* With the API, call `investigations.create`. See the
[Investigations API](/api-reference/investigations#start-an-investigation).
* With MCP, an agent can list, read, start, steer, and cancel investigations, and add notes.
An incident has one investigation. When you start an investigation for an incident that already has
one, Squasher returns the existing investigation.
## Steer or cancel an investigation
Add a note to give Squasher context, such as "We deployed the payments service at 10:02". A note
goes on the timeline.
A redirect changes the direction of the work, such as "Check the database connection pool first".
Squasher records the redirect and continues in that direction. A redirect also works after a
diagnosis: Squasher reopens the work to follow the new direction.
Cancel stops an active investigation. You can add a reason. You cannot steer a cancelled
investigation.
Project members can start, steer, and cancel investigations.
## Approve or reject an action
While it investigates, Squasher can propose an action. Squasher only proposes. It never runs an
action without a person's approval.
Each proposal shows:
* The exact target, such as one issue, one service, or one incident.
* Bounded parameters, such as the environment or the text of a status page update.
* A risk class: `low`, `medium`, or `high`.
* An expiry time. A proposal expires after 1 hour by default, and after at most 24 hours. You cannot
approve an expired proposal.
You approve an action right before it runs. When you approve, Squasher does these steps at once:
1. It checks the precondition, for example that the issue still exists. If the check fails, the
action does not run.
2. It calls the provider one time.
3. It checks the postcondition, for example that the new deployment exists.
Squasher calls the provider one time for one approval. It never calls the provider again for the
same approval, also when it does not see the result.
Each status change writes an entry to the organization audit log and to the investigation timeline
in the same step. When the action belongs to an incident, the incident timeline also shows it.
### When the result is unknown
Sometimes Squasher cannot see the result. For example, the provider does not answer in time after
Squasher sent the call. Then the action status is `unknown`, and the dashboard shows "Result
unknown — checking". Squasher does not run the action again. It reads the provider to find out if
the change happened, and then sets the status to `succeeded` or `failed`.
When the provider cannot tell, an owner or admin checks the provider and settles the result with
**Mark as succeeded** or **Mark as failed**. Squasher reads the provider first; your mark counts
only when the provider still cannot tell.
When you cancel an investigation, its open proposals expire.
Only an owner or admin of the project can approve, reject, or settle an action, and only from a
signed-in session: the dashboard, or the CLI after `squasher login`. The API refuses API keys for
these decisions, even a key with the `actions:approve` scope. Agents and MCP can read actions, but
they cannot approve, reject, or settle them.
## Supported actions
| Action | Provider | Target | Parameters | Risk |
| - | - | - | - | - |
| Open a fix pull request | GitHub | An issue | None. | medium |
| Redeploy a Railway service | Railway | A Railway service | `environment` (optional). | high |
| Restart a Railway service | Railway | A Railway service | `environment` (optional). | medium |
| Post a status page update | Status page | A published incident | `label` (`Investigating`, `Identified`, `Monitoring`, `Update`, or `Resolved`) and `message` (at most 4,000 characters). | medium |
A fix pull request starts an [auto-fix](/features/auto-fix) run. The run opens a pull request only
after its tests pass, and nothing merges without your review. A status page update needs an incident
that is published on a status page. Railway actions need a
[Railway connection](/integrations/railway).
## Use the CLI
```bash theme={null}
squasher investigations start --question "Why did checkout errors increase after 10:00?"
squasher investigations start --subject-kind incident --subject-id
squasher investigations list --view active
squasher investigations get
squasher investigations note "We deployed payments at 10:02"
squasher investigations redirect "Check the database pool first"
squasher investigations cancel --reason "Duplicate"
squasher actions list --status proposed
squasher actions approve
squasher actions reject --reason "Not during business hours"
squasher actions resolve --outcome failed --note "No new deployment in Railway"
```
Each command reads the project from `--project` or `SQUASHER_PROJECT_ID`. `squasher actions approve`
and `squasher actions reject` ask you to confirm. Add `--yes` to skip the prompt. Add `--json` to any
command for machine-readable output. Approve, reject, and resolve use the session from
`squasher login`, not an API key.
## Next steps
Start, steer, and decide from your own tools.
Ask follow-up questions in chat or Slack.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.