Skip to Content

Acknowledge an incident

POSThttps://api.respan.ai/api/pulses/incidents/{incident_id}/acknowledgement/

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

Servers

https://api.respan.ai: Respan API Server

Authentication

RespanApiKey

Use your Respan API key for Respan API authentication. Enter only the Respan API key value; clients send Authorization: Bearer <RESPAN_API_KEY>. For /api/responses, provider credentials such as Perplexity, OpenAI, or Azure OpenAI go in Settings -> Providers or respan_params.credential_override in the request body, not in this authentication field.

HTTP scheme: bearer; format: Respan API key.

HTTP
Authorization: Bearer $RESPAN_API_KEY

Path parameters

Parameter Type Required Description and constraints
incident_id string Required
Incident ID, from List incidents.
Example: "3c9d7e1a-58b2-4f0e-a6d4-91c2b7e3f805"

Request body

A request body is required.

application/json

Field Type Requirement Description and constraints
$ object Required body
Send at least one field.
Reference: #/components/schemas/ErrorIncidentAcknowledgementRequest
is_acknowledged boolean Optional
true to acknowledge, false to clear it.
Example: true
notes string Optional
Replaces the incident’s notes. Everyone in the organization can read them.
Maximum length: 4000
Example: "OpenAI org-level rate limit; requested an increase."

OpenAPI request schema

{
  "$ref": "#/components/schemas/ErrorIncidentAcknowledgementRequest"
}
Example
JSON
{ "is_acknowledged": true }

Responses

200

The updated incident.

application/json

Field Type Requirement Description and constraints
$ object Body
A window where one environment’s error rate for one fault domain rose well above its usual level.
Reference: #/components/schemas/ErrorIncident
id string Required in parent
Incident ID.
Example: "3c9d7e1a-58b2-4f0e-a6d4-91c2b7e3f805"
title string Required in parent
Main error class and environment, in words.
Example: "Provider rate limit in prod"
environment string Required in parent
Example: "prod"
fault_domain string Required in parent
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).
Reference: #/components/schemas/ErrorFaultDomain
Allowed: "user", "respan", "provider", "none"
Example: "respan"
started_at string Required in parent
Format: date-time
Example: "2026-09-30T14:02:00Z"
ended_at string or null Required in parent
End of the last elevated minute, or null while ongoing.
Format: date-time
Example: "2026-09-30T14:47:00Z"
duration_seconds integer Required in parent
From started_at to data_through_at.
Example: 2700
data_through_at string Required in parent
How far the evidence goes: ended_at once past; for an ongoing incident, the latest minute that is fully ingested.
Format: date-time
Example: "2026-09-30T14:47:00Z"
state string Required in parent
Allowed: "ongoing", "past"
Example: "past"
resolution_reason string or null Required in parent
Why it ended: the rate recovered, requests stopped, or the scope went silent. null while ongoing.
Allowed: "recovered", "no_traffic", "stale"
Example: "recovered"
severity string Required in parent
Allowed: "low", "medium", "high", "critical"
Example: "high"
trigger string Required in parent
spike for a sudden jump, drift for a sustained smaller rise.
Allowed: "spike", "drift"
Example: "spike"
peak_error_rate number Required in parent
A fraction from 0 to 1.
Example: 0.42
baseline_error_rate number Required in parent
A fraction from 0 to 1.
Example: 0.012
error_count integer Required in parent
Example: 1840
request_count integer Required in parent
Example: 9620
hot_bucket_count integer Required in parent
Minutes that tripped the detector.
Example: 31
error_class_breakdown object Required in parent
Failed requests per error class.
Example: {"provider_rate_limit":1702,"provider_overloaded":138}
error_class_breakdown.<key> integer Map value
-
dominant_error_class string Required in parent
Most common error class.
Example: "provider_rate_limit"
dominant_fingerprint string or null Required in parent
Error group with the most failures. Usually null in List incidents; Get an incident fills it.
Example: "9F3B2C1D4E5A6B7C"
impact object Required in parent
Reference: #/components/schemas/ErrorIncidentImpact
impact.error_count integer Required in parent
Failed requests in the incident window.
Example: 1840
impact.request_count integer Required in parent
All requests in the incident’s environment over the window.
Example: 9620
impact.error_rate number Required in parent
error_count / request_count. A fraction from 0 to 1.
Example: 0.191
impact.peak_error_rate number Required in parent
Highest one-minute error rate. A fraction from 0 to 1.
Example: 0.42
impact.baseline_error_rate number Required in parent
The scope’s usual error rate when the incident was detected. A fraction from 0 to 1.
Example: 0.012
impact.rate_delta number Required in parent
error_rate minus baseline_error_rate.
Example: 0.179
impact.rate_multiplier number or null Required in parent
error_rate / baseline_error_rate, or null when the baseline is 0.
Example: 15.9
impact.is_estimated boolean Required in parent
true when the counts are the detector’s estimate (incidents longer than 4 hours in List incidents). Get an incident returns exact counts.
Example: false
impact.affected_customers integer Optional
Distinct customers with a failed request. Only in Get an incident.
Example: 37
primary_error object Required in parent
-
primary_error.error_class string Required in parent
Example: "provider_rate_limit"
primary_error.fingerprint string or null Required in parent
Example: "9F3B2C1D4E5A6B7C"
acknowledged_at string or null Required in parent
Format: date-time
Example: null
is_acknowledged boolean Required in parent
Example: false
notes string Required in parent
Team notes. Visible to everyone in the organization.
Example: ""
created_at string Required in parent
Format: date-time
Example: "2026-09-30T14:05:12.448210Z"
updated_at string Required in parent
When the detector last evaluated the incident. Acknowledging or editing notes doesn’t change it.
Format: date-time
Example: "2026-09-30T14:52:03.118604Z"

OpenAPI response schema

{
  "$ref": "#/components/schemas/ErrorIncident"
}
Example
JSON
{ "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": null, "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, "is_estimated": false }, "primary_error": { "error_class": "provider_rate_limit", "fingerprint": null }, "acknowledged_at": "2026-09-30T14:20:41.902117Z", "is_acknowledged": true, "notes": "", "created_at": "2026-09-30T14:05:12.448210Z", "updated_at": "2026-09-30T14:52:03.118604Z" }

400

The body has neither field, or a field is invalid.

application/json

Field Type Requirement Description and constraints
$ object Body
-
$.<key> array<string> Map value
-
$.<key>[] string Array item
-

OpenAPI response schema

{
  "type": "object",
  "additionalProperties": {
    "type": "array",
    "items": {
      "type": "string"
    }
  }
}
Example
JSON
{ "non_field_errors": [ "provide at least one of: is_acknowledged, notes" ] }

403

Forbidden: the API key is missing, invalid or expired; the key doesn’t grant logs:update (Write access does).

application/json

Field Type Requirement Description and constraints
$ object Body
-
detail string Required in parent
-

OpenAPI response schema

{
  "type": "object",
  "required": [
    "detail"
  ],
  "properties": {
    "detail": {
      "type": "string"
    }
  }
}
Missing or invalid API key
JSON
{ "detail": "Your API key is invalid or expired, please check your API key in the platform settings." }
Key lacks the permission
JSON
{ "detail": "This API key does not have the 'logs:update' permission." }

404

No incident with this ID in your organization.

application/json

Field Type Requirement Description and constraints
$ object Body
-
error string Required in parent
-

OpenAPI response schema

{
  "type": "object",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string"
    }
  }
}
Example
JSON
{ "error": "incident not found" }

429

Rate limited. This endpoint allows 60 requests per minute per organization.

application/json

Field Type Requirement Description and constraints
$ object Body
-
detail string Required in parent
-

OpenAPI response schema

{
  "type": "object",
  "required": [
    "detail"
  ],
  "properties": {
    "detail": {
      "type": "string"
    }
  }
}
Example
JSON
{ "detail": "Request was throttled." }

OpenAPI source

The operation and referenced components below retain the complete OpenAPI definitions, including constraints and examples.

OpenAPI operation

{
  "summary": "Acknowledge an incident",
  "operationId": "updateIncidentAcknowledgement",
  "tags": [
    "Incidents"
  ],
  "description": "Acknowledges an incident or clears the acknowledgement, and sets its notes. Send either field or both.",
  "parameters": [
    {
      "name": "incident_id",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string"
      },
      "description": "Incident ID, from List incidents.",
      "example": "3c9d7e1a-58b2-4f0e-a6d4-91c2b7e3f805"
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ErrorIncidentAcknowledgementRequest"
        },
        "example": {
          "is_acknowledged": true
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "The updated incident.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ErrorIncident"
          },
          "example": {
            "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": null,
            "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,
              "is_estimated": false
            },
            "primary_error": {
              "error_class": "provider_rate_limit",
              "fingerprint": null
            },
            "acknowledged_at": "2026-09-30T14:20:41.902117Z",
            "is_acknowledged": true,
            "notes": "",
            "created_at": "2026-09-30T14:05:12.448210Z",
            "updated_at": "2026-09-30T14:52:03.118604Z"
          }
        }
      }
    },
    "400": {
      "description": "The body has neither field, or a field is invalid.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "additionalProperties": {
              "type": "array",
              "items": {
                "type": "string"
              }
            }
          },
          "example": {
            "non_field_errors": [
              "provide at least one of: is_acknowledged, notes"
            ]
          }
        }
      }
    },
    "403": {
      "description": "Forbidden: the API key is missing, invalid or expired; the key doesn't grant `logs:update` (Write access does).",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "detail"
            ],
            "properties": {
              "detail": {
                "type": "string"
              }
            }
          },
          "examples": {
            "invalidKey": {
              "summary": "Missing or invalid API key",
              "value": {
                "detail": "Your API key is invalid or expired, please check your API key in the platform settings."
              }
            },
            "missingPermission": {
              "summary": "Key lacks the permission",
              "value": {
                "detail": "This API key does not have the 'logs:update' permission."
              }
            }
          }
        }
      }
    },
    "404": {
      "description": "No incident with this ID in your organization.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "error"
            ],
            "properties": {
              "error": {
                "type": "string"
              }
            }
          },
          "example": {
            "error": "incident not found"
          }
        }
      }
    },
    "429": {
      "description": "Rate limited. This endpoint allows 60 requests per minute per organization.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "detail"
            ],
            "properties": {
              "detail": {
                "type": "string"
              }
            }
          },
          "example": {
            "detail": "Request was throttled."
          }
        }
      }
    }
  },
  "security": [
    {
      "RespanApiKey": []
    }
  ]
}

OpenAPI path metadata

{}

Referenced OpenAPI components

{
  "schemas": {
    "ErrorFaultDomain": {
      "type": "string",
      "enum": [
        "user",
        "respan",
        "provider",
        "none"
      ],
      "description": "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).",
      "example": "respan"
    },
    "ErrorIncident": {
      "type": "object",
      "description": "A window where one environment's error rate for one fault domain rose well above its usual level.",
      "required": [
        "id",
        "title",
        "environment",
        "fault_domain",
        "started_at",
        "ended_at",
        "duration_seconds",
        "data_through_at",
        "state",
        "resolution_reason",
        "severity",
        "trigger",
        "peak_error_rate",
        "baseline_error_rate",
        "error_count",
        "request_count",
        "hot_bucket_count",
        "error_class_breakdown",
        "dominant_error_class",
        "dominant_fingerprint",
        "impact",
        "primary_error",
        "acknowledged_at",
        "is_acknowledged",
        "notes",
        "created_at",
        "updated_at"
      ],
      "properties": {
        "id": {
          "type": "string",
          "description": "Incident ID.",
          "example": "3c9d7e1a-58b2-4f0e-a6d4-91c2b7e3f805"
        },
        "title": {
          "type": "string",
          "description": "Main error class and environment, in words.",
          "example": "Provider rate limit in prod"
        },
        "environment": {
          "type": "string",
          "example": "prod"
        },
        "fault_domain": {
          "$ref": "#/components/schemas/ErrorFaultDomain"
        },
        "started_at": {
          "type": "string",
          "format": "date-time",
          "example": "2026-09-30T14:02:00Z"
        },
        "ended_at": {
          "type": "string",
          "format": "date-time",
          "nullable": true,
          "description": "End of the last elevated minute, or `null` while ongoing.",
          "example": "2026-09-30T14:47:00Z"
        },
        "duration_seconds": {
          "type": "integer",
          "description": "From `started_at` to `data_through_at`.",
          "example": 2700
        },
        "data_through_at": {
          "type": "string",
          "format": "date-time",
          "description": "How far the evidence goes: `ended_at` once past; for an ongoing incident, the latest minute that is fully ingested.",
          "example": "2026-09-30T14:47:00Z"
        },
        "state": {
          "type": "string",
          "enum": [
            "ongoing",
            "past"
          ],
          "example": "past"
        },
        "resolution_reason": {
          "type": "string",
          "enum": [
            "recovered",
            "no_traffic",
            "stale"
          ],
          "nullable": true,
          "description": "Why it ended: the rate recovered, requests stopped, or the scope went silent. `null` while ongoing.",
          "example": "recovered"
        },
        "severity": {
          "type": "string",
          "enum": [
            "low",
            "medium",
            "high",
            "critical"
          ],
          "example": "high"
        },
        "trigger": {
          "type": "string",
          "enum": [
            "spike",
            "drift"
          ],
          "description": "`spike` for a sudden jump, `drift` for a sustained smaller rise.",
          "example": "spike"
        },
        "peak_error_rate": {
          "type": "number",
          "description": "A fraction from 0 to 1.",
          "example": 0.42
        },
        "baseline_error_rate": {
          "type": "number",
          "description": "A fraction from 0 to 1.",
          "example": 0.012
        },
        "error_count": {
          "type": "integer",
          "example": 1840
        },
        "request_count": {
          "type": "integer",
          "example": 9620
        },
        "hot_bucket_count": {
          "type": "integer",
          "description": "Minutes that tripped the detector.",
          "example": 31
        },
        "error_class_breakdown": {
          "type": "object",
          "additionalProperties": {
            "type": "integer"
          },
          "description": "Failed requests per error class.",
          "example": {
            "provider_rate_limit": 1702,
            "provider_overloaded": 138
          }
        },
        "dominant_error_class": {
          "type": "string",
          "description": "Most common error class.",
          "example": "provider_rate_limit"
        },
        "dominant_fingerprint": {
          "type": "string",
          "nullable": true,
          "description": "Error group with the most failures. Usually `null` in List incidents; Get an incident fills it.",
          "example": "9F3B2C1D4E5A6B7C"
        },
        "impact": {
          "$ref": "#/components/schemas/ErrorIncidentImpact"
        },
        "primary_error": {
          "type": "object",
          "required": [
            "error_class",
            "fingerprint"
          ],
          "properties": {
            "error_class": {
              "type": "string",
              "example": "provider_rate_limit"
            },
            "fingerprint": {
              "type": "string",
              "nullable": true,
              "example": "9F3B2C1D4E5A6B7C"
            }
          }
        },
        "acknowledged_at": {
          "type": "string",
          "format": "date-time",
          "nullable": true,
          "example": null
        },
        "is_acknowledged": {
          "type": "boolean",
          "example": false
        },
        "notes": {
          "type": "string",
          "description": "Team notes. Visible to everyone in the organization.",
          "example": ""
        },
        "created_at": {
          "type": "string",
          "format": "date-time",
          "example": "2026-09-30T14:05:12.448210Z"
        },
        "updated_at": {
          "type": "string",
          "format": "date-time",
          "description": "When the detector last evaluated the incident. Acknowledging or editing notes doesn't change it.",
          "example": "2026-09-30T14:52:03.118604Z"
        }
      }
    },
    "ErrorIncidentAcknowledgementRequest": {
      "type": "object",
      "description": "Send at least one field.",
      "properties": {
        "is_acknowledged": {
          "type": "boolean",
          "description": "`true` to acknowledge, `false` to clear it.",
          "example": true
        },
        "notes": {
          "type": "string",
          "maxLength": 4000,
          "description": "Replaces the incident's notes. Everyone in the organization can read them.",
          "example": "OpenAI org-level rate limit; requested an increase."
        }
      }
    },
    "ErrorIncidentImpact": {
      "type": "object",
      "required": [
        "error_count",
        "request_count",
        "error_rate",
        "peak_error_rate",
        "baseline_error_rate",
        "rate_delta",
        "rate_multiplier",
        "is_estimated"
      ],
      "properties": {
        "error_count": {
          "type": "integer",
          "description": "Failed requests in the incident window.",
          "example": 1840
        },
        "request_count": {
          "type": "integer",
          "description": "All requests in the incident's environment over the window.",
          "example": 9620
        },
        "error_rate": {
          "type": "number",
          "description": "`error_count` / `request_count`. A fraction from 0 to 1.",
          "example": 0.191
        },
        "peak_error_rate": {
          "type": "number",
          "description": "Highest one-minute error rate. A fraction from 0 to 1.",
          "example": 0.42
        },
        "baseline_error_rate": {
          "type": "number",
          "description": "The scope's usual error rate when the incident was detected. A fraction from 0 to 1.",
          "example": 0.012
        },
        "rate_delta": {
          "type": "number",
          "description": "`error_rate` minus `baseline_error_rate`.",
          "example": 0.179
        },
        "rate_multiplier": {
          "type": "number",
          "nullable": true,
          "description": "`error_rate` / `baseline_error_rate`, or `null` when the baseline is 0.",
          "example": 15.9
        },
        "is_estimated": {
          "type": "boolean",
          "description": "`true` when the counts are the detector's estimate (incidents longer than 4 hours in List incidents). Get an incident returns exact counts.",
          "example": false
        },
        "affected_customers": {
          "type": "integer",
          "description": "Distinct customers with a failed request. Only in Get an incident.",
          "example": 37
        }
      }
    }
  },
  "securitySchemes": {
    "RespanApiKey": {
      "type": "http",
      "scheme": "bearer",
      "bearerFormat": "Respan API key",
      "description": "Use your Respan API key for Respan API authentication. Enter only the Respan API key value; clients send Authorization: Bearer <RESPAN_API_KEY>. For /api/responses, provider credentials such as Perplexity, OpenAI, or Azure OpenAI go in Settings -> Providers or respan_params.credential_override in the request body, not in this authentication field.",
      "x-fern-bearer": {
        "name": "respanApiKey",
        "env": "RESPAN_API_KEY"
      }
    }
  }
}