Create retrospective

Create a retrospective (historical) status page incident.

Use this to backfill a completed incident with a reconstructed timeline of past updates, for example when migrating from another status page provider. Every update’s published_at must be in the past, the updates must be ordered chronologically (earliest first), and the final update must set incident_status to “resolved”.

Retrospective incidents never notify subscribers.

As this endpoint is intended for bulk historical backfill, it has a dedicated rate limit of 5 requests per second (with a burst allowance of 300 requests) per API key. If you exceed it you’ll receive a 429 response with a Retry-After header; back off and retry to resume your backfill.

This endpoint requires an API key with the “Create status page incidents, status page maintenance windows, and publish status page updates” scope.

POST /v2/status_page_retrospective_incidents

Create retrospective

cURL

curl --request POST \
  --url https://api.incident.io/v2/status_page_retrospective_incidents \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "idempotency_key": "historical-incident-2021-08-17",
  "name": "Elevated API latency",
  "status_page_id": "01FCNDV6P870EA6S7TK1DSYDG0",
  "updates": [
    {
      "component_statuses": [
        {
          "component_id": "01FCNDV6P870EA6S7TK1DSYDG2",
          "component_status": "operational"
        }
      ],
      "incident_status": "investigating",
      "message": "We are currently investigating reports of elevated error rates affecting our API.",
      "published_at": "2021-08-17T13:28:57.801578Z"
    }
  ]
}
'

import requests

url = "https://api.incident.io/v2/status_page_retrospective_incidents"

payload = {
    "idempotency_key": "historical-incident-2021-08-17",
    "name": "Elevated API latency",
    "status_page_id": "01FCNDV6P870EA6S7TK1DSYDG0",
    "updates": [
        {
            "component_statuses": [
                {
                    "component_id": "01FCNDV6P870EA6S7TK1DSYDG2",
                    "component_status": "operational"
                }
            ],
            "incident_status": "investigating",
            "message": "We are currently investigating reports of elevated error rates affecting our API.",
            "published_at": "2021-08-17T13:28:57.801578Z"
        }
    ]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    idempotency_key: 'historical-incident-2021-08-17',
    name: 'Elevated API latency',
    status_page_id: '01FCNDV6P870EA6S7TK1DSYDG0',
    updates: [
      {
        component_statuses: [{component_id: '01FCNDV6P870EA6S7TK1DSYDG2', component_status: 'operational'}],
        incident_status: 'investigating',
        message: 'We are currently investigating reports of elevated error rates affecting our API.',
        published_at: '2021-08-17T13:28:57.801578Z'
      }
    ]
  })
};

fetch('https://api.incident.io/v2/status_page_retrospective_incidents', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.incident.io/v2/status_page_retrospective_incidents",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'idempotency_key' => 'historical-incident-2021-08-17',
    'name' => 'Elevated API latency',
    'status_page_id' => '01FCNDV6P870EA6S7TK1DSYDG0',
    'updates' => [
        [
                'component_statuses' => [
                                [
                                                                'component_id' => '01FCNDV6P870EA6S7TK1DSYDG2',
                                                                'component_status' => 'operational'
                                ]
                ],
                'incident_status' => 'investigating',
                'message' => 'We are currently investigating reports of elevated error rates affecting our API.',
                'published_at' => '2021-08-17T13:28:57.801578Z'
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.incident.io/v2/status_page_retrospective_incidents"

	payload := strings.NewReader("{\n  \"idempotency_key\": \"historical-incident-2021-08-17\",\n  \"name\": \"Elevated API latency\",\n  \"status_page_id\": \"01FCNDV6P870EA6S7TK1DSYDG0\",\n  \"updates\": [\n    {\n      \"component_statuses\": [\n        {\n          \"component_id\": \"01FCNDV6P870EA6S7TK1DSYDG2\",\n          \"component_status\": \"operational\"\n        }\n      ],\n      \"incident_status\": \"investigating\",\n      \"message\": \"We are currently investigating reports of elevated error rates affecting our API.\",\n      \"published_at\": \"2021-08-17T13:28:57.801578Z\"\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.incident.io/v2/status_page_retrospective_incidents")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"idempotency_key\": \"historical-incident-2021-08-17\",\n  \"name\": \"Elevated API latency\",\n  \"status_page_id\": \"01FCNDV6P870EA6S7TK1DSYDG0\",\n  \"updates\": [\n    {\n      \"component_statuses\": [\n        {\n          \"component_id\": \"01FCNDV6P870EA6S7TK1DSYDG2\",\n          \"component_status\": \"operational\"\n        }\n      ],\n      \"incident_status\": \"investigating\",\n      \"message\": \"We are currently investigating reports of elevated error rates affecting our API.\",\n      \"published_at\": \"2021-08-17T13:28:57.801578Z\"\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.incident.io/v2/status_page_retrospective_incidents")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"idempotency_key\": \"historical-incident-2021-08-17\",\n  \"name\": \"Elevated API latency\",\n  \"status_page_id\": \"01FCNDV6P870EA6S7TK1DSYDG0\",\n  \"updates\": [\n    {\n      \"component_statuses\": [\n        {\n          \"component_id\": \"01FCNDV6P870EA6S7TK1DSYDG2\",\n          \"component_status\": \"operational\"\n        }\n      ],\n      \"incident_status\": \"investigating\",\n      \"message\": \"We are currently investigating reports of elevated error rates affecting our API.\",\n      \"published_at\": \"2021-08-17T13:28:57.801578Z\"\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

201

{
  "status_page_incident": {
    "component_impacts": [
      {
        "component_id": "01GW7P4ES31Q6V1ZQH321T0GJN",
        "component_status": "degraded_performance",
        "end_at": "2021-08-17T13:28:57.801578Z",
        "start_at": "2021-08-17T13:28:57.801578Z"
      }
    ],
    "id": "01FCNDV6P870EA6S7TK1DSYDG0",
    "incident_status": "investigating",
    "name": "Elevated API latency",
    "published_at": "2021-08-17T13:28:57.801578Z",
    "status_page_id": "01FCNDV6P870EA6S7TK1DSYDG0",
    "updates": [
      {
        "component_statuses": [
          {
            "component_id": "01FCNDV6P870EA6S7TK1DSYDG2",
            "component_status": "operational"
          }
        ],
        "id": "01FCNDV6P870EA6S7TK1DSYDG0",
        "incident_status": "investigating",
        "message": "abc123",
        "published_at": "2021-08-17T13:28:57.801578Z",
        "status_page_incident_id": "01FCNDV6P870EA6S7TK1DSYDG1"
      }
    ]
  }
}

🔑 Requires the status_pages.publish_updates scope.

Authorizations

Authorization · string · header · required

API key from your incident.io dashboard (Settings → API keys)

Body

application/json

idempotency_key · string · required

A unique key to de-duplicate requests. If you send a request with an idempotency_key that was already used, the original response will be returned.

Example:

"historical-incident-2021-08-17"

name · string · required

A title for the incident

Maximum string length: 200

Example:

"Elevated API latency"

status_page_id · string · required

ID of the status page. You can find this by calling the ListStatusPages endpoint.

Example:

"01FCNDV6P870EA6S7TK1DSYDG0"

updates · object[] · required

The reconstructed timeline of updates for this incident, ordered chronologically (earliest first). The final update must set incident_status to "resolved".

Show child attributes

Example:

[
  {
    "component_statuses": [
      {
        "component_id": "01FCNDV6P870EA6S7TK1DSYDG2",
        "component_status": "operational"
      }
    ],
    "incident_status": "investigating",
    "message": "We are currently investigating reports of elevated error rates affecting our API.",
    "published_at": "2021-08-17T13:28:57.801578Z"
  }
]

Response

201 - application/json

Created response.

status_page_incident · object

Show child attributes