Skip to content
FlagSwiftDocs

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.

Values for state
StateDescription
no_dataThere 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.
okMeasured, and below the threshold.
firingMeasured, 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_rate and latency_p95 look at the last windowHours hours including the hour still running. SDK error reports are not counted as API failures.
  • volume_drop and volume_spike compare the last windowHours complete 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_failures counts releases in the project (and environment, when set) that failed within the window. It is a plain count, so minSamples does not apply.
  • Leave environment out, 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#

Values for kind, with the allowed threshold
KindDescription
error_rateFailed API calls as a percentage of API requests. Threshold 0.1 to 100 (%). Default in the console 5.
latency_p95The 95th percentile latency in milliseconds, estimated from latency buckets. Threshold 5 to 60000 (ms). Default in the console 500.
volume_dropEvaluation volume fell by this percentage compared with the previous period. Threshold 1 to 100 (%). Default in the console 50.
volume_spikeEvaluation volume rose by this percentage compared with the previous period. Threshold 1 to 100000 (%). Default in the console 200.
release_failuresReleases 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#

POST/api/alerts

Authorization

alerts.manage

Body

  • projectIdstringRequired

    The project to watch. It cannot be archived.
  • namestringRequired

    Up to 100 characters.
  • kindstringRequired

    One of the kinds above.
  • thresholdnumberRequired

    Checked against the range of the kind; a value out of range is a 400 that says the range.
  • environmentstring

    Limit the rule to one environment, by name (up to 50 characters). Empty or left out means every environment.
  • windowHoursinteger

    How far back each check looks. One of 1, 2, 3, 6, 12 or 24. Default 1.
  • minSamplesinteger

    Fewest 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 minSamples that 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).
Request
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
  }'
201Created
{
  "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#

GET/api/alerts

Each 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.
Request
curl -s -b "auth_session=$SESSION" "$FLAGSWIFT_URL/api/alerts"
200OK
{
  "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#

PATCH/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

  • idstringRequired

    The rule id.

Body

  • namestring

    Up to 100 characters.
  • kindstring

    One of the kinds above. The threshold is re-checked against the new kind.
  • thresholdnumber

    In the range of the (new) kind.
  • environmentstring

    An existing environment name (up to 50 characters), or empty for every environment.
  • windowHoursinteger

    One of 1, 2, 3, 6, 12 or 24.
  • minSamplesinteger

    1 to 1,000,000.
  • enabledboolean

    false 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 kind alone), a window that is not allowed, a bad minSamples, 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”.
Request
# 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 }'
200OK
{
  "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#

DELETE/api/alerts/{id}

Authorization

alerts.manage

Path parameters

  • idstringRequired

    The 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”.
Request
curl -s -b "auth_session=$SESSION" -X DELETE "$FLAGSWIFT_URL/api/alerts/RULE_ID"
200OK
{ "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 holds alerts.read.
  • Creating, editing and deleting a rule is written to the audit log as alert.created, alert.updated and alert.deleted.

Common patterns#

Watch errors and failed releases for production#

bash
# 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#

bash
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#

bash
curl -s -b "auth_session=$SESSION" "$FLAGSWIFT_URL/api/alerts" \
  | jq '.data.items[] | select(.enabled and .state == "firing") | {name, lastValue, threshold, firingSince}'