Escalations

An escalation is a record of something that needs a human. When an investigation parks needing you, Polylane records the ask as an escalation and notifies you once. A second investigation blocked on the same remediation folds into the open escalation instead of notifying again.

Open Escalations in the console. The sidebar badge counts what is open.

Where escalations come from

Investigations raise escalations when they park on an attention outcome:

• Needs your action (needs_human_action): the fix requires something only you can do.
• Awaiting your decision (needs_decision): the agent needs a call from you before continuing.
• Agent stuck (failed): the investigation hit an error it could not work around.

Every escalation carries a source, the pipeline that raised it (investigation, credentials, connect, or autofix), a kind, a headline, and detail. You can also create escalations over the API to put your own asks on the same surface.

An escalation raised against an issue also lands on that issue's timeline, linking straight back to the escalation.

One ask, one record

A new escalation that matches an open one folds into it: the count increments, Last seen updates, and the origin joins the escalation's references. No second notification goes out.

Matching is exact on the dedupe key when the source has one, otherwise by text similarity, with an agent adjudicating borderline matches. It is scoped per source, so unrelated pipelines never suppress each other, and it lapses 24 hours after the last occurrence, so a long-quiet ask notifies again.

Clearing

Clearing marks an escalation handled: it leaves the open list and stops absorbing repeats, so a recurrence notifies again. Reopen it if the ask was not actually done. Clear and reopen live on the table's row menu, the detail page, and the API.

When an issue resolves, every open escalation referencing it clears itself.

Viewing escalations

The table at /escalations filters by status, source, and kind, searches headline, detail, and kind, and keeps filters, sort, and search in the URL so views are shareable. Quick presets: All, Open, Cleared.

Each escalation's detail page shows the ask, its occurrence count, first and last seen, an Origin list linking every issue and thread that raised it, and a lineage graph tracing the chain of events behind it.

From the API

# List open escalations in a workspace
curl "https://api.polylane.com/v1/escalations/<workspace-id>?status=open" \
  -H "Authorization: Bearer <api-key>"

# Clear one
curl -X PATCH "https://api.polylane.com/v1/escalations/<workspace-id>/<escalation-id>" \
  -H "Authorization: Bearer <api-key>" \
  -H "Content-Type: application/json" \
  -d '{"cleared": true}'

Listing supports status (open, cleared, all), search, source, kind, and id filters, plus paging and ordering. PATCH edits the kind, headline, and detail, and takes cleared: true or false to clear or reopen. POST /v1/escalations creates one, DELETE removes one. Reading requires the analytics:read API key scope, writing requires issues:write. See the API reference.

Try it from your coding agent:

Use Polylane to list the open escalations in my workspace and summarize what each one needs from me, with links to the issues behind them.

Related

• Investigations for the parked outcomes that raise escalations.
• Issues for the records escalations point back to.
• Notifications to control how the one notification reaches you.