Investigations

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.
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:

It checks the precondition, for example that the issue still exists. If the check fails, the action does not run.
It calls the provider one time.
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 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.

Use the CLI

squasher investigations start --question "Why did checkout errors increase after 10:00?"
squasher investigations start --subject-kind incident --subject-id <incident_id>
squasher investigations list --view active
squasher investigations get <investigation_id>
squasher investigations note <investigation_id> "We deployed payments at 10:02"
squasher investigations redirect <investigation_id> "Check the database pool first"
squasher investigations cancel <investigation_id> --reason "Duplicate"
squasher actions list --status proposed
squasher actions approve <action_id>
squasher actions reject <action_id> --reason "Not during business hours"
squasher actions resolve <action_id> --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.

Get started

Guides

What an investigation contains

Start an investigation

Steer or cancel an investigation

Approve or reject an action

When the result is unknown

Supported actions

Use the CLI

Next steps

Investigations API

Squasher Agent

​What an investigation contains

​Start an investigation

​Steer or cancel an investigation

​Approve or reject an action

​When the result is unknown

​Supported actions

​Use the CLI

​Next steps

Investigations API

Squasher Agent

What an investigation contains

Start an investigation

Steer or cancel an investigation

Approve or reject an action

When the result is unknown

Supported actions

Use the CLI

Next steps