diff --git a/src/content/changelogs/durable-objects.yaml b/src/content/changelogs/durable-objects.yaml
index 5f8e832e4463bb9..d1649c822480287 100644
--- a/src/content/changelogs/durable-objects.yaml
+++ b/src/content/changelogs/durable-objects.yaml
@@ -47,3 +47,8 @@ entries:
Durable Objects [request billing](/durable-objects/platform/pricing/#billing-metrics) applies a 20:1 ratio for incoming WebSocket messages. For example, 1 million Websocket received messages across connections would be charged as 50,000 Durable Objects requests.
This is a billing-only calculation and does not impact Durable Objects [metrics and analytics](/durable-objects/observability/graphql-analytics/).
+
+ - publish_date: "2024-02-15"
+ title: Optional `alarmInfo` parameter for Durable Object Alarms
+ description: |-
+ Durable Objects [Alarms](/durable-objects/api/alarms/) now have a new `alarmInfo` argument that provides more details about an alarm invocation, including the `retryCount` and `isRetry` to signal if the alarm was retried.
\ No newline at end of file
diff --git a/src/content/docs/durable-objects/api/alarms.mdx b/src/content/docs/durable-objects/api/alarms.mdx
index 555e26177fa630c..163296c204c7db5 100644
--- a/src/content/docs/durable-objects/api/alarms.mdx
+++ b/src/content/docs/durable-objects/api/alarms.mdx
@@ -54,10 +54,14 @@ Alarms can be used to build distributed primitives, like queues or batching of w
### `alarm`
-- `alarm()`:
+- alarm(`alarmInfo`)`:
- Called by the system when a scheduled alarm time is reached.
+ - The optional parameter `alarmInfo` object has two properties:
+ - `retryCount` : The number of times this alarm event has been retried.
+ - `isRetry` : A boolean value to indicate if the alarm has been retried. This value is `true` if this alarm event is a retry.
+
- The `alarm()` handler has guaranteed at-least-once execution and will be retried upon failure using exponential backoff, starting at 2 second delays for up to 6 retries. Retries will be performed if the method fails with an uncaught exception.
- This method can be `async`.
@@ -102,6 +106,18 @@ export class AlarmExample extends DurableObject {
}
```
+The following example shows how to use the `alarmInfo` property to identify if the alarm event has been attempted before.
+
+```js
+class MyDurableObject extends DurableObject {
+ async alarm(alarmInfo) {
+ if (alarmInfo?.retryCount != 0) {
+ console.log("This alarm event has been attempted ${alarmInfo?.retryCount} times before.");
+ }
+ }
+}
+```
+
## Related resources
- Understand how to [use the Alarms API](/durable-objects/examples/alarms-api/) in an end-to-end example.
diff --git a/src/content/docs/durable-objects/api/base.mdx b/src/content/docs/durable-objects/api/base.mdx
index 2ca7fc160aad13f..1a212a870593a94 100644
--- a/src/content/docs/durable-objects/api/base.mdx
+++ b/src/content/docs/durable-objects/api/base.mdx
@@ -35,10 +35,14 @@ export class MyDurableObject extends DurableObject {
### `alarm`
-- alarm():
+- alarm(`alarmInfo`):
- Called by the system when a scheduled alarm time is reached.
+ - The optional parameter `alarmInfo` object has two properties:
+ - `retryCount` : The number of times this alarm event has been retried.
+ - `isRetry` : A boolean value to indicate if the alarm has been retried. This value is `true` if this alarm event is a retry.
+
- The `alarm()` handler has guaranteed at-least-once execution and will be retried upon failure using exponential backoff, starting at two second delays for up to six retries. Retries will be performed if the method fails with an uncaught exception.
- This method can be `async`.