Alerts
Rules that watch your traffic and releases and fire when a number crosses a line.
Concepts#
How a rule is evaluated#
The server checks every enabled rule once a minute (unless SCHEDULER_ENABLED=false), and once straight after you create or edit it, so a new rule shows a value at once. A rule fires when its measured value reaches the threshold (greater than or equal) and enough requests back it up.
| State | Description |
|---|---|
| no_data | There is nothing to judge yet: no traffic in the window, fewer than minSamples observations, or (for volume rules) nothing in the previous period to compare with. New, edited and paused rules start here. It is never a false alarm. |
| ok | Measured, and below the threshold. |
| firing | Measured, at or above the threshold. firingSince says since when. |
Each change between firing and anything else is appended to history as fired or resolved with the value at that moment. Only the last 20 entries are kept. A rule that moves from ok to no_data records nothing, and lastValue and lastEvaluatedAt update on every check.
Windows and comparisons#
error_rateandlatency_p95look at the lastwindowHourshours including the hour still running. SDK error reports are not counted as API failures.volume_dropandvolume_spikecompare the lastwindowHourscomplete hours with the same number of hours before them, so a half-finished hour never looks like a drop. The value is the percentage change, never below 0.release_failurescounts releases in the project (and environment, when set) that failed within the window. It is a plain count, sominSamplesdoes not apply.- Leave
environmentout, or send it empty, to watch every environment of the project.
What happens when a rule fires#
Firing and resolving are always logged, and the rule shows as firing on the Alerts page and the Overview. If you set ALERT_WEBHOOK_URL it is also posted there, and, when an email provider is set up, it is emailed to everyone who holds alerts.manage. A failed notification never blocks anything.
What a rule can watch#
| Kind | Description |
|---|---|
| error_rate | Failed API calls as a percentage of API requests. Threshold 0.1 to 100 (%). Default in the console 5. |
| latency_p95 | The 95th percentile latency in milliseconds, estimated from latency buckets. Threshold 5 to 60000 (ms). Default in the console 500. |
| volume_drop | Evaluation volume fell by this percentage compared with the previous period. Threshold 1 to 100 (%). Default in the console 50. |
| volume_spike | Evaluation volume rose by this percentage compared with the previous period. Threshold 1 to 100000 (%). Default in the console 200. |
| release_failures | Releases that failed in the window, as a count. Threshold 1 to 1000 (failures). Default in the console 1. |
A rule belongs to a project, may be limited to one environment, and looks back over windowHours. minSamples holds it quiet until enough requests have been seen, so a quiet night does not fire an error-rate alert. The state is ok, firing or no_data.
Endpoints#
Create a rule#
/api/alertsAuthorization
alerts.manage
Body
projectIdstringRequiredThe project to watch. It cannot be archived.namestringRequiredUp to 100 characters.kindstringRequiredOne of the kinds above.thresholdnumberRequiredChecked against the range of the kind; a value out of range is a 400 that says the range.environmentstringLimit the rule to one environment, by name (up to 50 characters). Empty or left out means every environment.windowHoursintegerHow far back each check looks. One of 1, 2, 3, 6, 12 or 24. Default 1.minSamplesintegerFewest requests (or, for volume rules, evaluations in the earlier period) before the rule can fire. 1 to 1,000,000. Default 20. Ignored by release_failures.
Errors
- 400A missing or invalid field: “Project is required”, “Give the rule a name”, “Keep the name under 100 characters”, “Choose what to watch”, “Set a threshold”, “Threshold must be a number”, “Threshold must be between 0.1 and 100 %” (the range of that kind), “Window must be one of 1, 2, 3, 6, 12, 24 hours”, a
minSamplesthat is not a whole number from 1 to 1,000,000, an environment that does not exist, “This project is archived”, or a body that is not valid JSON. - 401No session, or it has expired (“Authentication required”).
- 403Your role lacks
alerts.manage, the organization is deactivated, or the request was blocked as cross-site (“Cross-site request blocked”). - 404The project does not exist in your organization.
- 409The organization already has 50 alert rules (the self-hosted cap).
curl -s -b "auth_session=$SESSION" \
-X POST "$FLAGSWIFT_URL/api/alerts" \
-H "Content-Type: application/json" \
-d '{
"projectId": "PROJECT_ID",
"name": "Production errors",
"kind": "error_rate",
"threshold": 5,
"environment": "production",
"windowHours": 1,
"minSamples": 100
}'{
"status": "success",
"message": "Alert rule created",
"data": {
"id": "b2f4a9c1-77d3-4e08-9a55-31c0de8a6f12",
"projectId": "PROJECT_ID",
"environment": "production",
"name": "Production errors",
"kind": "error_rate",
"threshold": 5,
"windowHours": 1,
"minSamples": 100,
"enabled": true,
"state": "ok",
"lastValue": 0.8,
"lastEvaluatedAt": "2026-10-03T10:15:00.000Z",
"firingSince": null,
"history": [],
"createdBy": "USER_ID",
"createdByEmail": "rm@example.com",
"createdAt": "2026-10-03T10:15:00.000Z",
"updatedAt": "2026-10-03T10:15:00.000Z"
}
}List rules#
/api/alertsEach rule comes with its current state and recent history of firing and resolving. There are no query parameters and no paging: every rule in the organization is returned, newest first (the limit is 50). counts.firing counts only enabled rules that are firing.
Authorization
alerts.read
Errors
- 401No session, or it has expired (“Authentication required”).
- 403Your role lacks
alerts.read, or the organization is deactivated.
curl -s -b "auth_session=$SESSION" "$FLAGSWIFT_URL/api/alerts"{
"status": "success",
"message": "OK",
"data": {
"items": [
{
"id": "b2f4a9c1-77d3-4e08-9a55-31c0de8a6f12",
"projectId": "PROJECT_ID",
"environment": "production",
"name": "Production errors",
"kind": "error_rate",
"threshold": 5,
"windowHours": 1,
"minSamples": 100,
"enabled": true,
"state": "firing",
"lastValue": 7.4,
"lastEvaluatedAt": "2026-10-03T10:15:00.000Z",
"firingSince": "2026-10-03T10:02:00.000Z",
"history": [
{ "at": "2026-10-02T14:20:00.000Z", "type": "fired", "value": 6.1 },
{ "at": "2026-10-02T14:48:00.000Z", "type": "resolved", "value": 1.2 },
{ "at": "2026-10-03T10:02:00.000Z", "type": "fired", "value": 5.3 }
],
"createdBy": "USER_ID",
"createdByEmail": "rm@example.com",
"createdAt": "2026-09-20T08:00:00.000Z",
"updatedAt": "2026-09-20T08:00:00.000Z"
}
],
"counts": { "firing": 1, "total": 1 }
}
}Edit or pause a rule#
/api/alerts/{id}Any field except projectId, plus enabled to pause or resume without losing the rule. Send only what changes; the rest is kept. Changing environment, kind, threshold, windowHours or minSamples, or pausing, resets the state to no_data because the old reading answered a different question; an enabled rule is then measured again straight away. The history is kept.
Authorization
alerts.manage
Path parameters
idstringRequiredThe rule id.
Body
namestringUp to 100 characters.kindstringOne of the kinds above. The threshold is re-checked against the new kind.thresholdnumberIn the range of the (new) kind.environmentstringAn existing environment name (up to 50 characters), or empty for every environment.windowHoursintegerOne of 1, 2, 3, 6, 12 or 24.minSamplesinteger1 to 1,000,000.enabledbooleanfalse pauses the rule, true resumes it.
Errors
- 400The same checks as create apply to the merged result: a threshold outside the kind's range (also after you change
kindalone), a window that is not allowed, a badminSamples, an unknown environment, or a name over 100 characters. - 401No session, or it has expired (“Authentication required”).
- 403Your role lacks
alerts.manage, the organization is deactivated, or the request was blocked as cross-site. - 404“Alert rule not found”.
# Pause a rule without losing it
curl -s -b "auth_session=$SESSION" \
-X PATCH "$FLAGSWIFT_URL/api/alerts/RULE_ID" \
-H "Content-Type: application/json" \
-d '{ "enabled": false }'{
"status": "success",
"message": "Alert rule saved",
"data": {
"id": "b2f4a9c1-77d3-4e08-9a55-31c0de8a6f12",
"name": "Production errors",
"kind": "error_rate",
"threshold": 5,
"enabled": false,
"state": "no_data",
"lastValue": null,
"firingSince": null,
"...": "other fields as in List rules"
}
}Delete a rule#
/api/alerts/{id}Authorization
alerts.manage
Path parameters
idstringRequiredThe rule id.
Errors
- 401No session, or it has expired (“Authentication required”).
- 403Your role lacks
alerts.manage, the organization is deactivated, or the request was blocked as cross-site. - 404“Alert rule not found”.
curl -s -b "auth_session=$SESSION" -X DELETE "$FLAGSWIFT_URL/api/alerts/RULE_ID"{ "status": "success", "message": "Alert rule deleted", "data": { "id": "b2f4a9c1-77d3-4e08-9a55-31c0de8a6f12" } }- Release managers and admins hold
alerts.manage; everyone who can see the project holdsalerts.read. - Creating, editing and deleting a rule is written to the audit log as
alert.created,alert.updatedandalert.deleted.
Common patterns#
Watch errors and failed releases for production#
# Page me when 5% or more of API calls fail over an hour, but only with 100+ calls
curl -s -b "auth_session=$SESSION" -X POST "$FLAGSWIFT_URL/api/alerts" \
-H "Content-Type: application/json" \
-d '{"projectId":"PROJECT_ID","name":"Prod errors","kind":"error_rate","threshold":5,"environment":"production","windowHours":1,"minSamples":100}'
# Any failed release in production in the last 6 hours
curl -s -b "auth_session=$SESSION" -X POST "$FLAGSWIFT_URL/api/alerts" \
-H "Content-Type: application/json" \
-d '{"projectId":"PROJECT_ID","name":"Prod release failed","kind":"release_failures","threshold":1,"environment":"production","windowHours":6}'Silence a rule during maintenance, then resume#
curl -s -b "auth_session=$SESSION" -X PATCH "$FLAGSWIFT_URL/api/alerts/RULE_ID" \
-H "Content-Type: application/json" -d '{"enabled":false}'
# ...after the work. The rule starts again from no_data and is measured at once.
curl -s -b "auth_session=$SESSION" -X PATCH "$FLAGSWIFT_URL/api/alerts/RULE_ID" \
-H "Content-Type: application/json" -d '{"enabled":true}'List what is firing now#
curl -s -b "auth_session=$SESSION" "$FLAGSWIFT_URL/api/alerts" \
| jq '.data.items[] | select(.enabled and .state == "firing") | {name, lastValue, threshold, firingSince}'