Importing historical incidents

​

Before you start

• Decide what to bring over. For each incident you’ll want a name, a severity, and the timestamps that matter to your reporting (when it was reported, when it was resolved). Summaries and custom fields are worth mapping too. Skip anything that doesn’t map cleanly. A sparse but accurate record beats a complete but messy one.
• Cleaning up a bad import is tedious. There’s no delete via the API. If an import goes wrong, you can select the incidents in the dashboard and mark them as test incidents to get them out of your reporting, but for a large batch that’s a chore you’d rather avoid. Import a small batch first, maybe five incidents, and check them in the dashboard before running the rest.
• Check your channel creation settings. Depending on your settings, each imported incident can create a Slack or Microsoft Teams channel. Five hundred imported incidents creating five hundred empty channels is not what anyone wants, and channel creation also determines which rate limit applies to you (see below). You can configure this per incident mode under channel creation settings in the dashboard.
• Talk to us about rate limits. Incident creation is deliberately rate limited to protect your account from runaway automations, which matters when you’re intentionally creating thousands of records. Contact support before a large import and we can temporarily raise the limits for your key.

​

Create the incidents

curl --request POST https://api.incident.io/v2/incidents \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "idempotency_key": "import-jira-4521",
    "visibility": "public",
    "mode": "retrospective",
    "name": "Database connection pool exhausted",
    "summary": "Connection pool hit its limit during the evening peak.",
    "severity_id": "01FCNDV6P870EA6S7TK1DSYDG0",
    "incident_timestamp_values": [
      {
        "incident_timestamp_id": "01FCNDV6P870EA6S7TK1DSYDG0",
        "value": "2024-03-02T18:22:00Z"
      }
    ]
  }'

• idempotency_key is required, and it’s your friend during an import: retrying a failed request with the same key won’t create a duplicate. Use something stable from your source system, like the original ticket reference.
• incident_timestamp_values is how you record when the incident actually happened. List your organization’s timestamps with the incident timestamps endpoint to find the IDs, then set the values that matter for your reporting. Without these, the incident is dated by when you imported it.
• custom_field_entries works the same as for any other incident, so you can carry over things like affected services or teams.

• slack_channel_id attaches an existing Slack channel to the incident instead of creating a new one. Useful if the original incident was run in Slack and the channel still exists.
• postmortem_document_url links an existing post-mortem document to the incident.
• external_id sets the incident number to match your previous system, so links and references keep making sense. This option needs enabling for your organization, so contact support first if you’d like to use it.

​

What retrospective mode does

• They start in your closed status, rather than going through triage or active response.
• They skip the post-incident flow, so no post-incident tasks are created for them.
• Workflows don’t run on them by default.

​

Pace the import

• Creating channels draws on Slack’s own rate limits, which are aggressive. An import that creates hundreds of channels can exhaust that allowance and stop channels being created for real incidents happening at the same time, so incidents that create channels are limited hard.
• The broader creation limit protects your account from runaway automations. A misconfigured script creating incidents in a loop can do a lot of damage. A limit that a human import finds slow is one that stops a machine doing real harm.

{
  "type": "rate_limit_reached",
  "status": 429,
  "errors": [
    {
      "code": "rate_limit_reached",
      "message": "You cannot create more than 10 incidents per hour. Please try again later."
    }
  ]
}

​

Check the result

curl --request GET 'https://api.incident.io/v2/incidents?mode%5Bone_of%5D=retrospective&page_size=25' \
  --header 'Authorization: Bearer <YOUR_API_KEY>'

​

Import the rest of your history

• Post-mortem documents: import existing write-ups as post-mortems with the import endpoint, which accepts markdown.
• Status page history: recreate your public status page timeline with retrospective status page incidents.
• Catalog: for services, teams, and other catalog data, use the catalog importer.
• Alerts: there’s currently no way to import historical alerts.