KEkeywordsai
Incidents

Acknowledge an incident

Changed on

Acknowledges an incident or clears the acknowledgement, and sets its notes. Send either field or both.

post/api/pulses/incidents/{incident_id}/acknowledgement/

Request

  • Base URL
    https://api.respan.ai
  • URL
    https://api.respan.ai/api/pulses/incidents/{incident_id}/acknowledgement/
  • Auth
    HTTP bearer

Path parameters

incident_idstring required

Incident ID, from List incidents.

Request body

is_acknowledgedboolean

true to acknowledge, false to clear it.

notesstring

Replaces the incident's notes. Everyone in the organization can read them.

Example request

{
  "is_acknowledged": true,
  "notes": "OpenAI org-level rate limit; requested an increase."
}

Response

The updated incident.

idstring required

Incident ID.

titlestring required

Main error class and environment, in words.

environmentstring required
fault_domain'user' | 'respan' | 'provider' | 'none' required

Whose fault the failure is, derived from error_class: user (your requests or your own provider keys), provider (the upstream provider), respan (Respan's gateway or managed capacity), or none (client cancellations).

started_atstring date-time required
ended_atstring date-time nullable required

End of the last elevated minute, or null while ongoing.

duration_secondsinteger required

From started_at to data_through_at.

data_through_atstring date-time required

How far the evidence goes: ended_at once past; for an ongoing incident, the latest minute that is fully ingested.

state'ongoing' | 'past' required
resolution_reason'recovered' | 'no_traffic' | 'stale' nullable required

Why it ended: the rate recovered, requests stopped, or the scope went silent. null while ongoing.

severity'low' | 'medium' | 'high' | 'critical' required
trigger'spike' | 'drift' required

spike for a sudden jump, drift for a sustained smaller rise.

peak_error_ratenumber required

A fraction from 0 to 1.

baseline_error_ratenumber required

A fraction from 0 to 1.

error_countinteger required
request_countinteger required
hot_bucket_countinteger required

Minutes that tripped the detector.

error_class_breakdownobject required

Failed requests per error class.

dominant_error_classstring required

Most common error class.

dominant_fingerprintstring nullable required

Error group with the most failures. Usually null in List incidents; Get an incident fills it.

acknowledged_atstring date-time nullable required
is_acknowledgedboolean required
notesstring required

Team notes. Visible to everyone in the organization.

created_atstring date-time required
updated_atstring date-time required

When the detector last evaluated the incident. Acknowledging or editing notes doesn't change it.

Example response

{
  "id": "3c9d7e1a-58b2-4f0e-a6d4-91c2b7e3f805",
  "title": "Provider rate limit in prod",
  "environment": "prod",
  "fault_domain": "respan",
  "started_at": "2026-09-30T14:02:00Z",
  "ended_at": "2026-09-30T14:47:00Z",
  "duration_seconds": 2700,
  "data_through_at": "2026-09-30T14:47:00Z",
  "state": "past",
  "resolution_reason": "recovered",
  "severity": "high",
  "trigger": "spike",
  "peak_error_rate": 0.42,
  "baseline_error_rate": 0.012,
  "error_count": 1840,
  "request_count": 9620,
  "hot_bucket_count": 31,
  "error_class_breakdown": {
    "provider_rate_limit": 1702,
    "provider_overloaded": 138
  },
  "dominant_error_class": "provider_rate_limit",
  "dominant_fingerprint": "9F3B2C1D4E5A6B7C",
  "impact": {
    "error_count": 1840,
    "request_count": 9620,
    "error_rate": 0.191,
    "peak_error_rate": 0.42,
    "baseline_error_rate": 0.012,
    "rate_delta": 0.179,
    "rate_multiplier": 15.9,
    "affected_customers": 37
  },
  "primary_error": {
    "error_class": "provider_rate_limit",
    "fingerprint": "9F3B2C1D4E5A6B7C"
  },
  "created_at": "2026-09-30T14:05:12.448210Z",
  "updated_at": "2026-09-30T14:52:03.118604Z"
}

Changes

  • c30bcb383ee8Revision changes
    • breaking

      request body became required

    • breaking

      the response property became nullable for the status

    • breaking

      the response property became nullable for the status

    • breaking

      the response property became nullable for the status

    • breaking

      the response property / became nullable for the status

    • breaking

      the response property / became nullable for the status

    • breaking

      the response property became nullable for the status

    • breaking

      the response's property format changed from double to no format for status

    • breaking

      the / response's property format changed from double to no format for status

    • breaking

      the / response's property format changed from double to no format for status

    • breaking

      the / response's property format changed from double to no format for status

    • breaking

      the / response's property format changed from double to no format for status

    • breaking

      the / response's property type changed from number null to number, and format from double to no format for status

    • breaking

      the response's property format changed from double to no format for status

    • breaking

      the response's property type changed from no type to string for status

    • warning

      added the new no_traffic enum value to the response property for the response status

    • warning

      added the new recovered enum value to the response property for the response status

    • warning

      added the new stale enum value to the response property for the response status

    • info

      api operation id incidents_updateIncidentAcknowledgement removed and replaced with updateIncidentAcknowledgement

    • info

      api tag Incidents added

    • info

      api tag incidents removed

    • info

      removed subschema #2 from the response property oneOf list for the response status

  • b830b79cfd52Revision changes
    • info

      endpoint added