incident.io holds the incident side of your engineering metrics: which services had incidents, how severe they were, and how long you took to recover. That’s the data behind DORA metrics like change failure rate and time to restore. Engineering metrics platforms like DX, Cortex, and Port read this data directly from our API, and join it with the deployment and code data they already collect from your CI/CD and source control.
Each tool does its own calculations, so the work on the incident.io side is making sure every incident records the service it affected and the timestamps your metrics are built from.
Set up your incident data
Record the affected service
Every tool joins incidents to its own services using a custom field on the incident. Use a Catalog-backed multi-select field (e.g. Affected services) so the values match the services in your Catalog rather than free text. See Custom fields to create one, and add it to your incident forms so responders fill it in.
If a responder already picks something the Catalog can map to a service, such as an affected product, set the field automatically so it’s never left empty. For incidents created from alerts, set it from the alert’s attributes. See Linking incidents to services.
Keep service names in your Catalog the same as the names in your engineering metrics tool, so payments-api in one
and Payments API in the other don’t end up as two services.
Define time to restore
MTTR is only as good as the timestamps it’s measured between. Duration metrics measure the time between two timestamps, and you choose which two. Measuring from when impact started, rather than when someone declared the incident, gives a more honest recovery time.
Configure timestamps and duration metrics in Settings → Response → Lifecycle, on the Timestamps and metrics tab, and turn on Enable validation for the metrics you report on, so a mistyped timestamp can’t produce a negative or inflated duration.
Decide which incidents count
The API leaves out test and tutorial incidents by default, along with incidents that were declined, canceled, or merged into another incident, so they don’t reach your metrics tool. Incidents still in triage are included. See Which incidents are counted for how this compares with Insights.
Each tool connects with an API key. Create a separate key for each tool, so you can see what each one is doing and revoke it on its own.
DX’s incident.io connector needs an API key with the View data and View catalog permissions, and the ID of your affected services field, which you can find with the list custom fields endpoint.
Cortex
Cortex’s incident.io integration lists the permissions its API key needs. To bring your Cortex services into incident.io’s Catalog, see Cortex.
Port
Port’s incident.io integration needs a read-only API key.
Any tool that can call an HTTP API can read the same data. Start with the API reference, and the list incidents endpoint. 
