AWS nova documentation change

Service: nova · 2025-05-28 · Documentation low

File: nova/latest/userguide/output-events.md

Summary

Added documentation for UsageEvent tracking token consumption metrics, including delta/total counts for input/output tokens. Updated event sequence numbering to include UsageEvent as first step.

Security assessment

The change introduces monitoring of token usage metrics but contains no references to vulnerabilities, access controls, encryption, or security mitigations. While useful for operational monitoring and cost tracking, there's no evidence this addresses a security flaw or adds security capabilities.

Diff

diff --git a/nova/latest/userguide/output-events.md b/nova/latest/userguide/output-events.md
index 0d52cf0cd..d10c85284 100644
--- a//nova/latest/userguide/output-events.md
+++ b//nova/latest/userguide/output-events.md
@@ -18,0 +19,2 @@ After audio generation completes (or is interrupted via barge-in), Amazon Nova S
+Throughout the response handling, `usageEvent` events are sent to track token consumption. These events contain detailed metrics on input tokens and output tokens (both speech and text), and their cumulative totals. Each `usageEvent` maintains the same `sessionId`, `promptName`, and `completionId` as other events in the conversation flow. The details section provides both incremental changes (delta) and running totals of token usage, enabling precise monitoring of the usage during the conversation.
+
@@ -29 +31,36 @@ The structure of the output event flow is described in this section.
-  1. `CompleteStartEvent`
+  1. `UsageEvent`
+    
+        "event": {
+        "usageEvent": {
+            "completionId": "string", // unique identifier for completion
+            "details": {
+                "delta": { // incremental changes since last event
+                    "input": {
+                        "speechTokens": number, // input speech tokens
+                        "textTokens": number // input text tokens
+                    },
+                    "output": {
+                        "speechTokens": number, // speech tokens generated
+                        "textTokens": number // text tokens generated
+                    }
+                },
+                "total": { // cumulative counts
+                    "input": {
+                        "speechTokens": number, // total speech tokens processed
+                        "textTokens": number // total text tokens processed
+                    },
+                    "output": {
+                        "speechTokens": number, // total speech tokens generated
+                        "textTokens": number // total text tokens generated
+                    }
+                }
+            },
+            "promptName": "string", // same unique identifier from promptStart event
+            "sessionId": "string", // unique identifier
+            "totalInputTokens": number, // cumulative input tokens
+            "totalOutputTokens": number, // cumulative output tokens
+            "totalTokens": number // total tokens in the session
+        }
+    }
+
+  2. `CompleteStartEvent`
@@ -39 +76 @@ The structure of the output event flow is described in this section.
-  2. `TextOutputContent`
+  3. `TextOutputContent`
@@ -83 +120 @@ The structure of the output event flow is described in this section.
-  3. `ToolUse`
+  4. `ToolUse`
@@ -128 +165 @@ The structure of the output event flow is described in this section.
-  4. `AudioOutputContent`
+  5. `AudioOutputContent`
@@ -175 +212 @@ The structure of the output event flow is described in this section.
-  5. `CompletionEndEvent`
+  6. `CompletionEndEvent`