OrbitsDocs
esc
    Open Orbits
    API reference · ObserveAlerts

    Alerts

    Alert rules on a project's metrics, their history, and the team's alert channels.

    An alert watches one of a project's metrics over a window and notifies the team's channels when it crosses its threshold, and again when it recovers. Preview a rule against recent data before saving it. See Alerts.

    The alert object

    Fields

    • idstringrequired
    • namestringrequired

      At most 60 characters.

    • metricstringrequired

      error-rate: 5xx responses as a share of requests, in %. p75, p99: response time in ms. requests: requests per minute.

      One of error-rate, p75, p99, requests.

    • directionstringrequired

      below only for requests.

      One of above, below.

    • thresholdnumberrequired
    • window_minutesintegerrequired

      One of 1, 5, 10, 30.

    • routesarray of stringrequired

      Routes as Observability names them; a trailing * matches a prefix. Empty for all routes.

    • channelsarray of stringrequired
    • onbooleanrequired
    • statestringrequired

      One of ok, firing.

    • sincestringrequired

      When it last fired or resolved, or was created or changed.

    • last_valuenumber or nullrequired

      The value at the last check; null before one, or with too little traffic.

    • checked_atstring or nullrequired
    • created_atstringrequired
    • updated_atstringrequired

    A project's alert rules and their state

    The Alerts card on Observability: every rule of the project, oldest first, with its state. A rule watches production's requests (the same traffic as Observability) and is checked every minute, at :30, over its last window_minutes whole minutes. It fires as soon as its value is past the line (above threshold, or below it for direction: below), and resolves after 3 checks in a row back on the right side. error-rate, p75 and p99 need 20 requests in the window to say anything: under that a rule can't fire, and last_value is null. A firing rule counts such a check toward resolving, unless what few requests there were are still past the line, and resolves with reason: quiet when the last of the 3 is one. webhook_configured says whether webhook can be offered as a channel.

    Permissions: Any team member. A non-member gets 404.

    GET/v1/teams/{team}/projects/{project}/alerts
    Read or full tokenReturns200OK

    Headers

    • Authorizationstringrequired

      Bearer and your API token: Bearer orb_live_….

    Path parameters

    • teamstringrequired

      Team slug or team_ id.

    • projectstringrequired

      Project slug or prj_ id.

    Response 200

    The rules.
    • itemsarray of Alertrequired
      Show 15 child fields
      • idstringrequired
      • namestringrequired

        At most 60 characters.

      • metricstringrequired

        error-rate: 5xx responses as a share of requests, in %. p75, p99: response time in ms. requests: requests per minute.

        One of error-rate, p75, p99, requests.

      • directionstringrequired

        below only for requests.

        One of above, below.

      • thresholdnumberrequired
      • window_minutesintegerrequired

        One of 1, 5, 10, 30.

      • routesarray of stringrequired

        Routes as Observability names them; a trailing * matches a prefix. Empty for all routes.

      • channelsarray of stringrequired
      • onbooleanrequired
      • statestringrequired

        One of ok, firing.

      • sincestringrequired

        When it last fired or resolved, or was created or changed.

      • last_valuenumber or nullrequired

        The value at the last check; null before one, or with too little traffic.

      • checked_atstring or nullrequired
      • created_atstringrequired
      • updated_atstringrequired
    • webhook_configuredbooleanrequired

      Whether the team has a webhook, so webhook can be chosen.

    Errors

    • 404Not found, or not visible to the caller (the two are indistinguishable on purpose).

    Every code is explained in Errors.

    curl "https://api.theorbits.app/v1/teams/my-team/projects/my-app/alerts" \
      -H "Authorization: Bearer $ORBITS_TOKEN"
    Response 200
    {
      "items": [
        {
          "id": "alr_7f3c2a1e-0d4b-4c55-9a7e-2b1f6c0d9e11",
          "name": "my-app",
          "metric": "error-rate",
          "direction": "above",
          "threshold": 1,
          "window_minutes": 1,
          "routes": [
            "routes"
          ],
          "channels": [
            "webhook"
          ],
          "on": false,
          "state": "ok",
          "since": "2026-11-10T09:30:00Z",
          "last_value": null,
          "checked_at": "2026-11-10T09:30:00Z",
          "created_at": "2026-11-10T09:30:00Z",
          "updated_at": "2026-11-10T09:30:00Z"
        }
      ],
      "webhook_configured": false
    }

    Create an alert rule

    The Create alert form. The rule starts ok and is first checked at the next :30. 422 names the field: a name already used in the project, direction: below for anything but requests, an error-rate threshold of 100 or more, a route that doesn't start with / or has a * anywhere but the end, or webhook in channels while the team has no webhook (webhook_configured on the list).

    Permissions: Owner, admin or member of the team. Viewers get 403. A non-member gets 404.

    POST/v1/teams/{team}/projects/{project}/alerts
    Full tokenNeeds Idempotency-KeyReturns201Created

    Headers

    • Authorizationstringrequired

      Bearer and your API token: Bearer orb_live_….

    • Idempotency-Keystringrequired

      A new value, such as a UUID, for each change. Resend with the same value and body to retry safely.

      From 8 to 128 characters.

    Path parameters

    • teamstringrequired

      Team slug or team_ id.

    • projectstringrequired

      Project slug or prj_ id.

    Body

    application/json
    • namestringrequired

      At most 60 characters.

    • metricstringrequired

      error-rate: 5xx responses as a share of requests, in %. p75, p99: response time in ms. requests: requests per minute.

      One of error-rate, p75, p99, requests.

    • directionstring

      One of above, below. Defaults to above.

    • thresholdnumberrequired

      At most 1000000.

    • window_minutesintegerrequired

      One of 1, 5, 10, 30.

    • routesarray of string

      At most 10 items.

    • channelsarray of stringrequired
    • onboolean

      Defaults to true.

    Response 201

    Created.
    • idstringrequired
    • namestringrequired

      At most 60 characters.

    • metricstringrequired

      error-rate: 5xx responses as a share of requests, in %. p75, p99: response time in ms. requests: requests per minute.

      One of error-rate, p75, p99, requests.

    • directionstringrequired

      below only for requests.

      One of above, below.

    • thresholdnumberrequired
    • window_minutesintegerrequired

      One of 1, 5, 10, 30.

    • routesarray of stringrequired

      Routes as Observability names them; a trailing * matches a prefix. Empty for all routes.

    • channelsarray of stringrequired
    • onbooleanrequired
    • statestringrequired

      One of ok, firing.

    • sincestringrequired

      When it last fired or resolved, or was created or changed.

    • last_valuenumber or nullrequired

      The value at the last check; null before one, or with too little traffic.

    • checked_atstring or nullrequired
    • created_atstringrequired
    • updated_atstringrequired

    Errors

    • 403Authenticated but not allowed in this team.
    • 404Not found, or not visible to the caller (the two are indistinguishable on purpose).
    • 422Validation failed, or the Idempotency-Key was reused with a different body.

    Every code is explained in Errors.

    curl -X POST "https://api.theorbits.app/v1/teams/my-team/projects/my-app/alerts" \
      -H "Authorization: Bearer $ORBITS_TOKEN" \
      -H "Idempotency-Key: $(uuidgen)" \
      -H "Content-Type: application/json" \
      -d '{
        "name": "my-app",
        "metric": "error-rate",
        "threshold": 1,
        "window_minutes": 1,
        "channels": [
          "webhook"
        ]
      }'
    Response 201
    {
      "id": "alr_7f3c2a1e-0d4b-4c55-9a7e-2b1f6c0d9e11",
      "name": "my-app",
      "metric": "error-rate",
      "direction": "above",
      "threshold": 1,
      "window_minutes": 1,
      "routes": [
        "routes"
      ],
      "channels": [
        "webhook"
      ],
      "on": false,
      "state": "ok",
      "since": "2026-11-10T09:30:00Z",
      "last_value": null,
      "checked_at": "2026-11-10T09:30:00Z",
      "created_at": "2026-11-10T09:30:00Z",
      "updated_at": "2026-11-10T09:30:00Z"
    }

    How much traffic a draft rule would see

    For the Create and Edit forms. median_requests is the median number of requests a window of this size held over the last 24 hours on these routes (minutes without traffic count as none). When it is under minimum_requests (20 for error-rate, p75 and p99; 0 for requests), warn under the window field, for example "These routes get about 6 requests in 1 minute. The rule won't fire until a window has 20. Try 5 or 10 minutes." It is a warning: the form can still be saved. value is what the rule would measure now, or null with too little traffic.

    Permissions: Owner, admin or member of the team. Viewers get 403. A non-member gets 404.

    POST/v1/teams/{team}/projects/{project}/alerts/preview
    Full tokenNeeds Idempotency-KeyReturns200OK

    Headers

    • Authorizationstringrequired

      Bearer and your API token: Bearer orb_live_….

    • Idempotency-Keystringrequired

      A new value, such as a UUID, for each change. Resend with the same value and body to retry safely.

      From 8 to 128 characters.

    Path parameters

    • teamstringrequired

      Team slug or team_ id.

    • projectstringrequired

      Project slug or prj_ id.

    Body

    application/json
    • metricstringrequired

      error-rate: 5xx responses as a share of requests, in %. p75, p99: response time in ms. requests: requests per minute.

      One of error-rate, p75, p99, requests.

    • directionstring

      One of above, below.

    • window_minutesintegerrequired

      One of 1, 5, 10, 30.

    • routesarray of string

      At most 10 items.

    Response 200

    The traffic and the value now.
    • median_requestsnumberrequired

      Median requests per window over the last 24 hours.

    • minimum_requestsintegerrequired

      What a window needs before the rule acts: 20, or 0 for requests.

    • valuenumber or nullrequired

      The value over the last window, or null with too little traffic.

    Errors

    • 403Authenticated but not allowed in this team.
    • 404Not found, or not visible to the caller (the two are indistinguishable on purpose).
    • 422Validation failed, or the Idempotency-Key was reused with a different body.
    • 503A store this endpoint reads is unreachable. Try again shortly.

    Every code is explained in Errors.

    curl -X POST "https://api.theorbits.app/v1/teams/my-team/projects/my-app/alerts/preview" \
      -H "Authorization: Bearer $ORBITS_TOKEN" \
      -H "Idempotency-Key: $(uuidgen)" \
      -H "Content-Type: application/json" \
      -d '{
        "metric": "error-rate",
        "window_minutes": 1
      }'
    Response 200
    {
      "median_requests": 1,
      "minimum_requests": 1,
      "value": null
    }

    Change or switch an alert rule

    The rule's switch, and the Edit dialog. Send only what changes. Any change, switching it off or on included, starts the rule again from ok. A rule that was firing first resolves, so a receiver sees its incident close: reason: changed for an edit, off when switched off. Changing metric away from requests sets direction to above unless one is sent. 422 as for create.

    Permissions: Owner, admin or member of the team. Viewers get 403. A non-member gets 404.

    PATCH/v1/teams/{team}/projects/{project}/alerts/{alert}
    Full tokenReturns200OK

    Headers

    • Authorizationstringrequired

      Bearer and your API token: Bearer orb_live_….

    Path parameters

    • teamstringrequired

      Team slug or team_ id.

    • projectstringrequired

      Project slug or prj_ id.

    • alertstringrequired

      An alr_ id from GET .../alerts.

    Body

    application/json
    • namestring

      At most 60 characters.

    • metricstring

      error-rate: 5xx responses as a share of requests, in %. p75, p99: response time in ms. requests: requests per minute.

      One of error-rate, p75, p99, requests.

    • directionstring

      One of above, below.

    • thresholdnumber

      At most 1000000.

    • window_minutesinteger

      One of 1, 5, 10, 30.

    • routesarray of string

      At most 10 items.

    • channelsarray of string
    • onboolean

    Response 200

    The rule as saved.
    • idstringrequired
    • namestringrequired

      At most 60 characters.

    • metricstringrequired

      error-rate: 5xx responses as a share of requests, in %. p75, p99: response time in ms. requests: requests per minute.

      One of error-rate, p75, p99, requests.

    • directionstringrequired

      below only for requests.

      One of above, below.

    • thresholdnumberrequired
    • window_minutesintegerrequired

      One of 1, 5, 10, 30.

    • routesarray of stringrequired

      Routes as Observability names them; a trailing * matches a prefix. Empty for all routes.

    • channelsarray of stringrequired
    • onbooleanrequired
    • statestringrequired

      One of ok, firing.

    • sincestringrequired

      When it last fired or resolved, or was created or changed.

    • last_valuenumber or nullrequired

      The value at the last check; null before one, or with too little traffic.

    • checked_atstring or nullrequired
    • created_atstringrequired
    • updated_atstringrequired

    Errors

    • 403Authenticated but not allowed in this team.
    • 404Not found, or not visible to the caller (the two are indistinguishable on purpose).
    • 422Validation failed, or the Idempotency-Key was reused with a different body.

    Every code is explained in Errors.

    curl -X PATCH "https://api.theorbits.app/v1/teams/my-team/projects/my-app/alerts/alr_01jc8x6e4mq2v7r9y3t5b0zp8w" \
      -H "Authorization: Bearer $ORBITS_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
        "name": "my-app",
        "metric": "error-rate",
        "direction": "above",
        "threshold": 1,
        "window_minutes": 1,
        "routes": [
          "routes"
        ],
        "channels": [
          "webhook"
        ],
        "on": false
      }'
    Response 200
    {
      "id": "alr_7f3c2a1e-0d4b-4c55-9a7e-2b1f6c0d9e11",
      "name": "my-app",
      "metric": "error-rate",
      "direction": "above",
      "threshold": 1,
      "window_minutes": 1,
      "routes": [
        "routes"
      ],
      "channels": [
        "webhook"
      ],
      "on": false,
      "state": "ok",
      "since": "2026-11-10T09:30:00Z",
      "last_value": null,
      "checked_at": "2026-11-10T09:30:00Z",
      "created_at": "2026-11-10T09:30:00Z",
      "updated_at": "2026-11-10T09:30:00Z"
    }

    Delete an alert rule

    Deletes the rule and its history. A rule that was firing sends alert.resolved with reason: deleted first.

    Permissions: Owner, admin or member of the team. Viewers get 403. A non-member gets 404.

    DELETE/v1/teams/{team}/projects/{project}/alerts/{alert}
    Full tokenReturns204No Content

    Headers

    • Authorizationstringrequired

      Bearer and your API token: Bearer orb_live_….

    Path parameters

    • teamstringrequired

      Team slug or team_ id.

    • projectstringrequired

      Project slug or prj_ id.

    • alertstringrequired

      An alr_ id from GET .../alerts.

    Response 204

    Deleted. No body.

    Errors

    • 403Authenticated but not allowed in this team.
    • 404Not found, or not visible to the caller (the two are indistinguishable on purpose).

    Every code is explained in Errors.

    curl -X DELETE "https://api.theorbits.app/v1/teams/my-team/projects/my-app/alerts/alr_01jc8x6e4mq2v7r9y3t5b0zp8w" \
      -H "Authorization: Bearer $ORBITS_TOKEN"
    HTTP/1.1 204 No Content

    When a rule fired and resolved

    A rule's history, newest first, kept 90 days, with how each notification went (deliveries: one per channel, pending while it is still being tried, up to 5 times over about 30 minutes).

    Permissions: Any team member. A non-member gets 404.

    GET/v1/teams/{team}/projects/{project}/alerts/{alert}/events
    Read or full tokenReturns200OK

    Headers

    • Authorizationstringrequired

      Bearer and your API token: Bearer orb_live_….

    Path parameters

    • teamstringrequired

      Team slug or team_ id.

    • projectstringrequired

      Project slug or prj_ id.

    • alertstringrequired

    Query parameters

    • limitinteger

      From 1 to 100. Defaults to 20.

    • cursorstring

    Response 200

    One page of events.
    • itemsarray of AlertEventrequired
      Show 6 child fields
      • idstringrequired
      • kindstringrequired

        One of fired, resolved.

      • reasonstring or nullrequired

        Why it resolved: its value came back, its traffic went too quiet to measure (value is null), or it was changed, switched off or deleted while firing.

        One of recovered, quiet, changed, off, deleted.

      • valuenumber or nullrequired
      • atstringrequired
      • deliveriesarray of AlertDeliveryrequired
        Show 4 child fields
        • channelstringrequired

          webhook: the team's webhook. email: the team's owners, admins and members.

          One of webhook, email.

        • statusstringrequired

          One of pending, delivered, failed.

        • errorstring or nullrequired

          Why the last try failed, e.g. "The webhook answered 500".

        • atstring or nullrequired

          When it was delivered or given up on.

    • next_cursorstring or nullrequired

    Errors

    • 404Not found, or not visible to the caller (the two are indistinguishable on purpose).
    • 422Validation failed, or the Idempotency-Key was reused with a different body.

    Every code is explained in Errors.

    curl "https://api.theorbits.app/v1/teams/my-team/projects/my-app/alerts/alr_01jc8x6e4mq2v7r9y3t5b0zp8w/events" \
      -H "Authorization: Bearer $ORBITS_TOKEN"
    Response 200
    {
      "items": [
        {
          "id": "id",
          "kind": "fired",
          "reason": "recovered",
          "value": null,
          "at": "2026-11-10T09:30:00Z",
          "deliveries": [
            {
              "channel": "webhook",
              "status": "pending",
              "error": null,
              "at": "2026-11-10T09:30:00Z"
            }
          ]
        }
      ],
      "next_cursor": null
    }

    The team's alert webhook

    The webhook every rule with the webhook channel sends to, one per team, or null. The secret is never shown again after it is made; secret_last4 identifies it.

    Permissions: Owner or admin of the team. Members and viewers get 403 (the list's webhook_configured tells them whether one is set). A non-member gets 404.

    GET/v1/teams/{team}/alert-channels
    Read or full tokenReturns200OK

    Headers

    • Authorizationstringrequired

      Bearer and your API token: Bearer orb_live_….

    Path parameters

    • teamstringrequired

      Team slug or team_ id.

    Response 200

    The webhook, or null.
    • webhookAlertWebhook or nullrequired
      Show 3 child fields
      • urlstringrequired
      • secret_last4stringrequired
      • updated_atstringrequired

    Errors

    • 403Authenticated but not allowed in this team.
    • 404Not found, or not visible to the caller (the two are indistinguishable on purpose).

    Every code is explained in Errors.

    curl "https://api.theorbits.app/v1/teams/my-team/alert-channels" \
      -H "Authorization: Bearer $ORBITS_TOKEN"
    Response 200
    {
      "webhook": {
        "url": "https://my-app.theorbits.app",
        "secret_last4": "secret-last4",
        "updated_at": "2026-11-10T09:30:00Z"
      }
    }

    Set the team's alert webhook

    Sets the URL (https only). The first time, or with rotate_secret, a new secret is made and returned in secret, this once; the old one stops working at once. Otherwise secret is null and the secret is kept.

    Every request Orbits sends is a JSON POST with X-Signature-256: sha256=<hex> (HMAC-SHA256 of the raw body with the secret), X-Delivery-Id (the same on every retry of one notification) and X-Orbits-Event (alert.fired, alert.resolved or alert.test). The body is an AlertWebhookPayload. A 2xx answer is delivered; anything else, or no answer in 10 seconds, is tried again. Redirects aren't followed, and addresses that aren't on the public internet are refused. The webhook-receiver template verifies these as they are.

    Permissions: Owner or admin of the team. Members and viewers get 403. A non-member gets 404.

    PUT/v1/teams/{team}/alert-channels/webhook
    Full tokenReturns200OK

    Headers

    • Authorizationstringrequired

      Bearer and your API token: Bearer orb_live_….

    Path parameters

    • teamstringrequired

      Team slug or team_ id.

    Body

    application/json
    • urlstringrequired

      An https URL without a user name or password.

      At most 2000 characters.

    • rotate_secretboolean

      Defaults to false.

    Response 200

    Saved.
    • webhookAlertWebhookrequired
      Show 3 child fields
      • urlstringrequired
      • secret_last4stringrequired
      • updated_atstringrequired
    • secretstring or nullrequired

      The new secret (64 hex characters), shown this once; null when it was kept.

    Errors

    • 403Authenticated but not allowed in this team.
    • 404Not found, or not visible to the caller (the two are indistinguishable on purpose).
    • 422Validation failed, or the Idempotency-Key was reused with a different body.

    Every code is explained in Errors.

    curl -X PUT "https://api.theorbits.app/v1/teams/my-team/alert-channels/webhook" \
      -H "Authorization: Bearer $ORBITS_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
        "url": "https://my-app.theorbits.app"
      }'
    Response 200
    {
      "webhook": {
        "url": "https://my-app.theorbits.app",
        "secret_last4": "secret-last4",
        "updated_at": "2026-11-10T09:30:00Z"
      },
      "secret": null
    }

    Remove the team's alert webhook

    Notifications still waiting for the webhook fail with "The team has no webhook".

    Permissions: Owner or admin of the team. Members and viewers get 403. A non-member gets 404.

    DELETE/v1/teams/{team}/alert-channels/webhook
    Full tokenReturns204No Content

    Headers

    • Authorizationstringrequired

      Bearer and your API token: Bearer orb_live_….

    Path parameters

    • teamstringrequired

      Team slug or team_ id.

    Response 204

    Removed. No body.

    Errors

    • 403Authenticated but not allowed in this team.
    • 404Not found, or not visible to the caller (the two are indistinguishable on purpose).

    Every code is explained in Errors.

    curl -X DELETE "https://api.theorbits.app/v1/teams/my-team/alert-channels/webhook" \
      -H "Authorization: Bearer $ORBITS_TOKEN"
    HTTP/1.1 204 No Content

    Send a test event to the webhook

    Sends a signed alert.test now and says how it went: delivered for a 2xx answer, otherwise the receiver's status (null when nothing answered) and an error to show. 404 when the team has no webhook.

    Permissions: Owner or admin of the team. Members and viewers get 403. A non-member gets 404.

    POST/v1/teams/{team}/alert-channels/webhook/test
    Full tokenNeeds Idempotency-KeyReturns200OK

    Headers

    • Authorizationstringrequired

      Bearer and your API token: Bearer orb_live_….

    • Idempotency-Keystringrequired

      A new value, such as a UUID, for each change. Resend with the same value and body to retry safely.

      From 8 to 128 characters.

    Path parameters

    • teamstringrequired

      Team slug or team_ id.

    Response 200

    How the test went.
    • deliveredbooleanrequired
    • statusinteger or nullrequired
    • errorstring or nullrequired

    Errors

    • 403Authenticated but not allowed in this team.
    • 404Not found, or not visible to the caller (the two are indistinguishable on purpose).

    Every code is explained in Errors.

    curl -X POST "https://api.theorbits.app/v1/teams/my-team/alert-channels/webhook/test" \
      -H "Authorization: Bearer $ORBITS_TOKEN" \
      -H "Idempotency-Key: $(uuidgen)"
    Response 200
    {
      "delivered": false,
      "status": null,
      "error": null
    }

    Was this page helpful?

    Updated