Working with Alerts in the AlertOps SDKs

Overview

Relevant for Developers automating alert triage and response

An alert is opened by an inbound integration or by hand. It carries messages, and each message fans out to recipients as notifications over their contact methods, timed by the alert's escalation policy. alerts covers listing, manual creation, the lifecycle (assign, close, hold, snooze, merge, promote to incident) and the material around an alert: notes, attachments, custom fields, postmortems and drafts.

Key benefits:

• Listing that works the first time — alerts.list_recent sets viewBy A and an exclusive createdTo of tomorrow, and the paginated variants (…All / …Iter) follow the alerts cursor.
• Lifecycle helpers — reopen, hold, cancel and resolve hide the numeric status codes.
• A working acknowledge path — auth.act_on_link runs the Acknowledge, Assign, Escalate or Close button from a notification.

Reading the operation names

Relevant for Developers using any of the five AlertOps SDKs

This guide applies to every AlertOps SDK. It names each operation by its resource path and operation name, such as groups.members.add_users, lists positional arguments in order, and shows request bodies and options as JSON. Where a task needs real code, the example is given in all five languages. Each SDK spells the same call in its own style:

• Names follow each language's style: update_basic is updateBasic in TypeScript and Java, UpdateBasic in Go and UpdateBasicAsync in .NET. Go keeps initialisms upper case (create_api is CreateAPI, post_to_url is PostToURL).
• Paginated operations also have variants that collect every page or iterate lazily (…All / …Iter; in Python, .all() and .iter() on the operation).
• Helpers that look something up return null (None in Python, nil in Go) when nothing matches. **ensure helpers** return the record together with a flag that says whether it was created.
• Errors are the same classes in every SDK, such as NotFoundError and BadRequestError.
• Code examples come in the order Python, TypeScript, Go, Java, .NET. Each assumes a client named ao (and, in Go, a ctx and a function that returns error), created as in that SDK's Getting Started article.

For one language's details, see Calling the API from Python, TypeScript, Go, Java or .NET.

Before you start

Relevant for Developers preparing a tenant for alert automation

• Manual alerts need an escalation policy with quick_launch set to true (see Escalation Policies and Response Plays with the AlertOps SDKs).
• Ingested alerts come from an integration's api_url (see Inbound Integrations, Alert Ingestion and Heartbeats with the AlertOps SDKs).
• Use test recipients (for example @example.com users) while you build: creating, resending and escalating alerts sends real notifications.

List and export alerts

Relevant for Developers reading alerts for reports and triage

GET /alerts filters on creation date. Pass both dates as YYYY-MM-DD, and pass viewBy A for all alerts. The newest alerts come first. For example, alerts.list with these fields lists open alerts from four days:

{"viewBy": "A", "createdFrom": "2026-11-01", "createdTo": "2026-11-05", "status": "1", "limit": 100}

• alerts.list_recent(1) lists the last day's alerts with viewBy A and createdTo set to tomorrow.
• alerts.list_recent(7, {all_pages: true, priority: "Critical"}) follows every page and filters by priority.
• alerts.export({viewBy: "A", createdFrom: "2026-11-03", createdTo: "2026-11-05"}) returns CSV text with the same filters.

A new alert can take a few seconds to appear in the list, so poll briefly after creating or ingesting one.

Create a manual alert

Relevant for Developers raising alerts from scripts and tools

alerts.create with this body returns the full alert, including alert_id, the first message_id and the status Open:

{
  "escalation_policy": 31337,
  "priority": "Critical",
  "subject": "Disk full on db-01",
  "description": "/var is at 98%",
  "recipients": [{"recipient_type": "Group", "recipient_id": 12345},
                 {"recipient_type": "User", "recipient_id": 101}]
}

escalation_policy is the id of a policy with quick_launch true. recipient_type is User or Group. Pass response_play with a play id instead of escalation_policy to drive the alert with a response play.

Read an alert

Relevant for Anyone inspecting what happened to an alert

Figure 1. An alert ingested through the SDK's API integration, after the SDK closed it. The summary shows owner Alice, the SDK-E2E NOC escalation policy and the technical service; the stats show 1 inbound event, 3 users and 3 notified, with 0 acknowledged.

Manage the lifecycle

Relevant for Developers assigning, closing and parking alerts

Assigning an alert takes ownership and stops the escalation ladder through the default Stop Delivery on Assignment or Closed workflow. In the SDK-E2E run, an alert assigned straight away notified only the Primary; Secondary and Manager were never paged.

alerts.set_status(alert_id, {status: "<id>"}) takes a status id as a string and returns no body. The ids, from lookups.alert_status():

Merge, unmerge and promote

{"message_text": "Customer impact", "escalation_policy_id": 31337, "topic_id": null,
 "recipients": [{"recipient_id": 101, "recipient_type": "User"}]}

merge, unmerge, promote_to_incident and set_status return no body; re-read the alert to see the change.

Messages and notifications

Relevant for Developers following deliveries and nudging an escalation

• cancel works only while deliveries are still pending; afterwards it answers 400 "Nothing to Cancel".
• escalate and escalate_to_next_group need a next user or group and the first delivery to have gone out. Right after create they answer "There is no user/group to escalate to".
• To add people to an open alert, use alerts.add_recipients(alert_id, {…}) with the body below. The key is recipient, not recipient_id, and a recipient already on the alert gives 400 "Create not complete".

{"escalation_policy": 31337, "response_play": null,
 "recipients": [{"recipient_type": "User", "recipient": "102", "send_message": true}]}

Acknowledge an alert

Relevant for Developers building acknowledge buttons, bots and responders

The new UI uses an alert-level call instead, alerts.acknowledge_alert(alert_id, {device_id: "", user_id: …}) (POST /alerts/{id}/acknowledge). It shows the button only when the alert's acknowledge_allowed is true. On this tenant the call answers 400 "Alert not acknowledged.", so it is held back by the same server-side gate. alerts.technical_services(alert_id) (v3) lists the technical services an alert belongs to.

Acknowledgement works through the token in the notification. Each alert email has Acknowledge, Assign, Escalate and Close buttons that link to https://app.alertops.com/<account>/alert/acknowledge?Token=<32 hex>&TokenType=DLV. Pass that link to auth.act_on_link:

1. Copy the button link from the delivered notification (an Outlook safelinks-wrapped copy works too).
2. Call auth.act_on_link(link).
3. Read the result: the action (acknowledge) and the alert summary, whose message_status is now ACK and alert_status is still Open.

Python

action, summary = ao.auth.act_on_link(link)
print(action, summary["message_status"], summary["alert_status"])   # acknowledge ACK Open

TypeScript

const [action, summary] = await ao.auth.actOnLink(link);
console.log(action, summary.message_status, summary.alert_status);   // acknowledge ACK Open

Go

action, summary, err := ao.Auth.ActOnLink(ctx, link, nil)
if err != nil {
	return err
}
fmt.Println(action, alertops.Get(summary, "message_status"), alertops.Get(summary, "alert_status")) // acknowledge ACK Open

Java

PlatformHelpers.LinkResult result = ao.auth().actOnLink(link);
System.out.println(result.action() + " " + result.alert().path("message_status").asText()
    + " " + result.alert().path("alert_status").asText());   // acknowledge ACK Open

.NET

var (action, summary) = await ao.Auth.ActOnLinkAsync(link);
Console.WriteLine($"{action} {summary?["message_status"]} {summary?["alert_status"]}");   // acknowledge ACK Open

Verified with a real alert email on 2026-11-03: the message went PACK → ACK and the alert stayed Open. Acknowledging says "I saw it" and the ladder keeps going; assign or close the alert to stop it.

To call the steps yourself, split the link into its action, account, token and token type, then use the token operations:

• auth.alert_by_token({tokenType, account, token}) returns {message_status, alert_status, can_assign, …}.
• auth.acknowledge_by_token({account, token, token_type, contact: "", resolution: ""}) acknowledges.
• auth.close_by_token({account, token, token_type, contact: "", resolution: "Fixed"}) closes.

Acknowledge and close by token were exercised live; assign and escalate use the same mechanism but weren't sent, to avoid extra emails.

Notes, attachments, fields, postmortems and drafts

Relevant for Developers enriching alerts and closing the loop

• update_fields takes a bare list. An entry without alert_field_id blanks the field.
• The legacy alerts.update needs status (a name) and applies only source fields (source, source_id …). It ignores subject, priority and description.

Postmortems exist only on closed alerts: postmortem.get answers 400 "is not closed" while the alert is open, then {} until one is saved. Create and update need every active postmortem field, so use alerts.postmortem.save(alert_id, {…}), which fills them in:

{"name": "db-01 disk", "owner": 101, "status": "Draft",
 "impact_start": "2026-11-03T09:00", "impact_end": "2026-11-03T09:30", "duration": 30,
 "values": {"Root Cause": "Log rotation disabled"}}

Drafts: alerts.drafts.create(body) takes the same body as alerts.create and returns an alert in status "Message Draft". The draft_id the draft endpoints use is that alert's message_id. drafts.find(subject) looks one up and drafts.send(draft_id, body) opens it. Deleting a draft leaves the backing alert in "Message Draft": it can't be closed, only cancelled (alerts.cancel, or resolve, which does that for you).

Operation Reference

Relevant for Developers looking up an operation

Workflow and outbound logs (workflow_log, outbound_log, run_outbound_action) and the legacy preview are in each SDK's method reference.

Best Practices

Relevant for Anyone automating alerts in production

Query deliberately

• Always pass viewBy A and a createdTo of tomorrow, or use list_recent.
• Keep date ranges short and filter by integration or escalationPolicy instead of scanning everything.

Stop escalation the right way

• Assign or close an alert to stop the ladder; acknowledging alone lets it continue.
• Clean up with resolve, which handles drafts and already-closed alerts without errors.

Handle notification links as secrets

• Don't log or store action links longer than needed; anyone with the link can act on the alert.
• Act on each link once and read the result from the returned summary.

Configuration Examples

Relevant for Starting templates for alert automation

Example 1 — Triage: assign today's open critical alerts

Example 2 — Count today's alerts per integration

Iterate alerts.list with its lazy paginated variant and {viewBy: "A", createdFrom: "2026-11-04", createdTo: "2026-11-05"}, and count the alerts by integration.id.

Example 3 — Chat bot: acknowledge from a pasted link

Call auth.act_on_link(link). On success, reply with the action and the summary's message_status and alert_status. On BadRequestError, reply with the error's messages, for example ["Message not acknowledged."] for a reused token.

Troubleshooting

Relevant for Anyone debugging alert calls

The list is empty, or today's alerts are missing

• viewBy is missing, so only the caller's own alerts come back. Pass viewBy A.
• createdTo is today; it is exclusive. Pass tomorrow, or use list_recent.
• The alert is a few seconds old. Poll again shortly.

Create fails with "Invalid Escalation Policy or Response Play value"

• The policy's quick_launch is false, or the id isn't a policy. Set quick_launch to true or use a quick-launch policy.

Acknowledge fails with 400 "Alert is not enabled for acknowledge"

• The web action is refused on this tenant. Use auth.act_on_link(link) with the notification's button link.

Acknowledge by token fails with 400 "Message not acknowledged."

• The token was already used to acknowledge. Read auth.alert_by_token(…): message_status is ACK already.

Token calls fail with 400 "Token is invalid"

• The link was truncated or rewritten. Pass the full link, or the safelinks URL, to the link parser and check the token is 32 hex characters.

Escalate fails with "There is no user/group to escalate to"

• The first delivery hasn't gone out yet, or there's no next member or group. Wait for messages.notifications to show a delivery, then retry.

Cancel fails with 400 "Nothing to Cancel"

• Every delivery of the message has already been sent.

Postmortem calls fail

• 400 "is not closed": close the alert first. A list of missing field names: use postmortem.save, which sends every active field.

A draft can't be closed

• Draft-backed alerts can only be cancelled. Use alerts.cancel(alert_id) or resolve.

Related Articles

• Inbound Integrations, Alert Ingestion and Heartbeats with the AlertOps SDKs
• Escalation Policies and Response Plays with the AlertOps SDKs
• Workflows, Outbound Integrations and Maintenance Windows with the AlertOps SDKs
• Getting Started with the AlertOps Python SDK
• Getting Started with the AlertOps TypeScript SDK

Need help?

Email support@alertops.com or contact your AlertOps representative.