Importing historical incidents

• Blameless
• FireHydrant
• ServiceNow
• Rootly

​

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.
• Plan for the rate limit. Incident creation is deliberately rate limited to protect your account from runaway automations, which matters when you’re intentionally creating thousands of records. Imports run at 300 incidents per hour per API key (see pace the import below), so do the arithmetic before you start.

​

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. The incident’s created_at always records when you ran the import and can’t be changed, so these values are what place the incident correctly in your history. Durations and insights are computed from them, meaning a well-imported incident reports exactly like one that happened natively.
• 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 never create a Slack or Microsoft Teams channel, so an import won’t fill your workspace with empty channels. If the original incident’s channel still exists, attach it with slack_channel_id.
• 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

{
  "type": "rate_limit_reached",
  "status": 429,
  "errors": [
    {
      "code": "rate_limit_reached",
      "message": "You cannot create more than 300 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.