Overview
Retrospective state is readable and writable through the API — useful for a completion dashboard of your own, a nudge bot, or a script that skips a step that does not apply to a class of incident. Full request and response schemas for every endpoint are in the API Reference tab. This page covers what the reference cannot: which status vocabulary applies where, and which of them means what.Three Status Vocabularies
The most common mistake with this API is treating retrospective status as one thing. It is three, at three different levels, and they overlap without matching.Incident-level: retrospective_progress_status
On the incident, describing the retrospective as a whole:
Also available in Liquid as
{{ incident.retrospective_progress_status }} — see Incident Variables.
Step-level: status
On each incident retrospective step, describing one step:
Document-level: status
On the retrospective document itself — the write-up, not its progress:
This is the status retrospective workflows trigger on. When a retrospective workflow says “Status Updated”, it means this status, not the incident’s progress.
The Overlap Problem
Before you write a query, decide which of the three questions you are asking: how far along is the retrospective (incident), is this particular step done (step), or has the write-up been shared (document).Reading Retrospective State
The incident’s ownretrospective_progress_status attribute gives the summary. Fetch the incident and read it — no separate call is required for the headline state.
For step detail, GET /v1/incident_retrospective_steps/{id} returns one step:
skippable records whether the process marked this step required, and the API treats it as information rather than as a constraint — a PUT setting status to skipped succeeds either way. Rootly’s own UI offers the skip action only where skippable is true, so a script that ignores the flag can leave a retrospective in a state the UI would not have allowed. Read it and honor it.
Finding a Step ID
There is no endpoint that lists an incident’s retrospective steps directly. They hang off the retrospective, so fetch that and ask for the steps:included array carries one entry per step, and its id is the STEP_ID used below. To get the RETROSPECTIVE_ID in the first place, list retrospectives with GET /v1/post_mortems or read one from its incident.
The resource is named
post_mortems in the API even where the product says retrospective. The two mean the same thing — see the status vocabularies above.Updating a Step
PUT /v1/incident_retrospective_steps/{id} updates one step. This is how a script marks a step done or skips one that does not apply.
Steps are the unit of change. There is no endpoint that sets the incident’s
retrospective_progress_status directly — it follows from the state of the steps beneath it. Drive the steps and the incident-level status keeps itself current.Configuring the Process
Everything above is about one incident’s retrospective. The shape every retrospective takes — which steps exist, in what order, with what defaults — is configured separately, and also has API endpoints:- Retrospective processes —
/v1/retrospective_processes, plus its groups and steps - Process steps —
/v1/retrospective_steps/{id} - Retrospective configurations —
/v1/retrospective_configurations
Exporting
Exporting a finished retrospective — to PDF, Confluence, and the other destinations — is a separate capability, covered in Exporting Retrospectives.Related Pages
Configuring Processes
The steps and structure every retrospective inherits.
Exporting Retrospectives
Getting a finished retrospective out of Rootly.