> ## Documentation Index
> Fetch the complete documentation index at: https://docs.incident.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Send incident data to your engineering metrics tools

> Put your incident data next to your delivery data, so MTTR and change failure rate sit alongside the rest of your engineering metrics.

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](#dx), [Cortex](#cortex), and [Port](#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](/catalog/catalog-setup) rather than free text. See [Custom fields](/incidents/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](/incidents/custom-fields#set-a-custom-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](/insights/how-we-measure-incidents#linking-incidents-to-services).

<Tip>
  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.
</Tip>

### Define time to restore

MTTR is only as good as the timestamps it's measured between. [Duration metrics](/insights/how-we-measure-incidents#duration-metrics) measure the time between two [timestamps](/insights/how-we-measure-incidents#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**](https://app.incident.io/~/settings/lifecycle?tab=timestamps), 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](/insights/how-we-measure-incidents#which-incidents-are-counted) for how this compares with Insights.

## Connect your tool

Each tool connects with an [API key](/admin/api-keys). Create a separate key for each tool, so you can see what each one is doing and revoke it on its own.

### DX

[DX's incident.io connector](https://docs.getdx.com/connectors/incident-io/) 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](/api-reference/custom-fields-v2/list).

### Cortex

[Cortex's incident.io integration](https://docs.cortex.io/ingesting-data-into-cortex/integrations/incidentio) lists the permissions its API key needs. To bring your Cortex services into incident.io's Catalog, see [Cortex](/integrations/cortex).

### Port

[Port's incident.io integration](https://docs.port.io/context-lake/ingestion/ingest-data-into-port/native-integrations/incident-management/incident-io) needs a read-only API key.

### Other tools

Any tool that can call an HTTP API can read the same data. Start with the [API reference](/api-reference/introduction), and the [list incidents endpoint](/api-reference/incidents-v2/list).