Acknowledge an incident
https://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.
Authorization: Bearer $RESPAN_API_KEYPath parameters
incident_id string RequiredExample:
"3c9d7e1a-58b2-4f0e-a6d4-91c2b7e3f805"Request body
A request body is required.
application/json
$ object Required body
Reference:
#/components/schemas/ErrorIncidentAcknowledgementRequestis_acknowledged boolean Optionaltrue to acknowledge, false to clear it.Example:
truenotes string OptionalMaximum length:
4000Example:
"OpenAI org-level rate limit; requested an increase."OpenAPI request schema
{
"$ref": "#/components/schemas/ErrorIncidentAcknowledgementRequest"
}Example
{
"is_acknowledged": true
}Responses
200
The updated incident.
application/json
$ object Body
Reference:
#/components/schemas/ErrorIncidentid string Required in parentExample:
"3c9d7e1a-58b2-4f0e-a6d4-91c2b7e3f805"title string Required in parentExample:
"Provider rate limit in prod"environment string Required in parent"prod"fault_domain string Required in parenterror_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/ErrorFaultDomainAllowed:
"user", "respan", "provider", "none"Example:
"respan"started_at string Required in parentdate-timeExample:
"2026-09-30T14:02:00Z"ended_at string or null Required in parentnull while ongoing.Format:
date-timeExample:
"2026-09-30T14:47:00Z"duration_seconds integer Required in parentstarted_at to data_through_at.Example:
2700data_through_at string Required in parentended_at once past; for an ongoing incident, the latest minute that is fully ingested.Format:
date-timeExample:
"2026-09-30T14:47:00Z"state string Required in parent"ongoing", "past"Example:
"past"resolution_reason string or null Required in parentnull while ongoing.Allowed:
"recovered", "no_traffic", "stale"Example:
"recovered"severity string Required in parent"low", "medium", "high", "critical"Example:
"high"trigger string Required in parentspike for a sudden jump, drift for a sustained smaller rise.Allowed:
"spike", "drift"Example:
"spike"peak_error_rate number Required in parentExample:
0.42baseline_error_rate number Required in parentExample:
0.012error_count integer Required in parent1840request_count integer Required in parent9620hot_bucket_count integer Required in parentExample:
31error_class_breakdown object Required in parent
Example:
{"provider_rate_limit":1702,"provider_overloaded":138}error_class_breakdown.<key> integer Map valuedominant_error_class string Required in parentExample:
"provider_rate_limit"dominant_fingerprint string or null Required in parentnull in List incidents; Get an incident fills it.Example:
"9F3B2C1D4E5A6B7C"impact object Required in parent
#/components/schemas/ErrorIncidentImpactimpact.error_count integer Required in parentExample:
1840impact.request_count integer Required in parentExample:
9620impact.error_rate number Required in parenterror_count / request_count. A fraction from 0 to 1.Example:
0.191impact.peak_error_rate number Required in parentExample:
0.42impact.baseline_error_rate number Required in parentExample:
0.012impact.rate_delta number Required in parenterror_rate minus baseline_error_rate.Example:
0.179impact.rate_multiplier number or null Required in parenterror_rate / baseline_error_rate, or null when the baseline is 0.Example:
15.9impact.is_estimated boolean Required in parenttrue when the counts are the detector’s estimate (incidents longer than 4 hours in List incidents). Get an incident returns exact counts.Example:
falseimpact.affected_customers integer OptionalExample:
37primary_error object Required in parent
primary_error.error_class string Required in parent"provider_rate_limit"primary_error.fingerprint string or null Required in parent"9F3B2C1D4E5A6B7C"acknowledged_at string or null Required in parentdate-timeExample:
nullis_acknowledged boolean Required in parentfalsenotes string Required in parentExample:
""created_at string Required in parentdate-timeExample:
"2026-09-30T14:05:12.448210Z"updated_at string Required in parentFormat:
date-timeExample:
"2026-09-30T14:52:03.118604Z"OpenAPI response 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
The body has neither field, or a field is invalid.
application/json
$ object Body
$.<key> array<string> Map value
$.<key>[] string Array itemOpenAPI response schema
{
"type": "object",
"additionalProperties": {
"type": "array",
"items": {
"type": "string"
}
}
}Example
{
"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
$ object Body
detail string Required in parentOpenAPI response schema
{
"type": "object",
"required": [
"detail"
],
"properties": {
"detail": {
"type": "string"
}
}
}Missing or invalid API key
{
"detail": "Your API key is invalid or expired, please check your API key in the platform settings."
}Key lacks the permission
{
"detail": "This API key does not have the 'logs:update' permission."
}404
No incident with this ID in your organization.
application/json
$ object Body
error string Required in parentOpenAPI response schema
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
}
}
}Example
{
"error": "incident not found"
}429
Rate limited. This endpoint allows 60 requests per minute per organization.
application/json
$ object Body
detail string Required in parentOpenAPI response schema
{
"type": "object",
"required": [
"detail"
],
"properties": {
"detail": {
"type": "string"
}
}
}Example
{
"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"
}
}
}
}