How does the Incident.io integration work?

Last updated: December 19, 2025

With the Incident.io integration, you can automatically pull incident data into your analytics dashboards. This allows you to track metrics by organization and team giving you deeper insight into operational performance.

Step 1: Connect to Incident.io

  1. Navigate to Integrations in your settings.

  2. Select Incident.io and click Connect.

  3. Enter your API Key (never stored in plain text).

  4. Click Connect to establish the integration.

Tip: You can generate an API key from your Incident.io account settings.

Step 2: Configure Team Mappings

Once connected, map your internal teams to Incident.io fields:

  1. Go to Team Mappings.

  2. Select the relevant Team Field in Incident.io (for example, Proximal Owner, Detection Method, Root Cause, Affected Teams).

  3. Assign each of your internal teams to the corresponding Incident.io value.

This ensures incidents are properly attributed to the right teams and dimensions in analytics.

Step 3: View Metrics in Analytics

After setup, incident metrics will appear in your dashboards under Analytics → Teams / People.

You can filter by:

  • Organization (all incidents across your company)

  • Team (drill down to a specific group)

  • Time range (weekly, monthly, quarterly trends)

Incident Metrics (available with Incident.io)

  • Incidents per week

  • PR cycle time

  • Issue cycle time

  • Total incidents

How are incidents attributed to teams in Span?

For Integration-Sourced Incidents

When incidents come from external platforms (like incident.io):

  • Custom field mapping in integration settings defines which fields contain team information

  • During ingestion, Span extracts team data from the mapped custom fields

  • If no mapping exists or the field is empty, it falls back to service-based or org-level attribution

In the event that no mapping exists, here is the attribution logic in order of priority:

1. Explicit Team Ownership (Primary)

  • Teams can be directly assigned as owners via the owners field when creating/updating incidents through Span's API

  • These explicit assignments are stored as OwnedByGroup relationships

  • This is the most direct and preferred method

2. Service-Based Attribution (Implicit)

  • If no explicit team owners exist, incidents are attributed to the teams that own the linked services

  • When you associate services with an incident, Span automatically queries which teams own those services

  • Those teams become attributed to the incident through the OwnedByServiceGroup relationship

  • Logic: If an incident affects a service, the team owning that service is responsible

3. Organization-Level Fallback (Default)

  • If an incident has neither explicit owners nor linked services, it's attributed to the root organization team

  • This ensures every incident has at least one team attribution for metrics calculation

Why This Design?

This multi-tier approach handles the reality that:

  • Not all incidents have associated services tracked

  • Some incidents are managed without detailed service mapping

  • Every incident needs a guaranteed team attribution for DORA metrics (like Change Failure Rate)

The system ensures comprehensive coverage while allowing flexibility in how teams manage incident data.