DOC-API-MODEL-schema-pntuu08p80#overview
LLMGenerationCompletedEvent
Event emitted when a generation run reaches a terminal state. The event context identifies the associated conversation.
Meaning and usage
Section ID: DOC-API-MODEL-schema-pntuu08p80#meaning
See the definition above.
Usage profiles
Section ID: DOC-API-MODEL-schema-pntuu08p80#fields
| Usage | Fields and validation |
|---|---|
| In requests | View fields |
| In responses | View fields |
In requests
Section ID: DOC-API-MODEL-schema-pntuu08p80#request
API JSON uses JSON field names (camelCase).
| Field | Type | Presence | Meaning |
|---|---|---|---|
Section ID: DOC-API-MODEL-schema-pntuu08p80#request-field-runidrunId | string | Optional | Unique identifier for the workflow run |
Section ID: DOC-API-MODEL-schema-pntuu08p80#request-field-statusstatus | string (WORKFLOW_STATUS_RUNNING, WORKFLOW_STATUS_COMPLETED, WORKFLOW_STATUS_FAILED, WORKFLOW_STATUS_TIMED_OUT, WORKFLOW_STATUS_CANCELED) or integer (int32) | Optional; explicit presence | Terminal status of the run |
Section ID: DOC-API-MODEL-schema-pntuu08p80#request-field-loopcountloopCount | string (int64) | Optional | Number of agent loops/steps executed Pattern: ^-?\d+$. |
Section ID: DOC-API-MODEL-schema-pntuu08p80#request-field-durationmsdurationMs | string (int64) | Optional | End-to-end run duration in milliseconds Pattern: ^-?\d+$. |
Section ID: DOC-API-MODEL-schema-pntuu08p80#request-field-usageusage | Usage | Optional | Optional usage accounting for the run |
Section ID: DOC-API-MODEL-schema-pntuu08p80#request-field-errorerror | RpcError | Optional | Structured error for FAILED/TIMED_OUT/CANCELED runs. |
Section ID: DOC-API-MODEL-schema-pntuu08p80#request-field-usagebymodelusageByModel | Array of UsageByModel | Optional | Per-model breakdown of the same usage usage aggregates. Additive: usage stays the run-level total so existing consumers are unaffected, while billing keys its charges on model. Empty when the producer predates it. |
Section ID: DOC-API-MODEL-schema-pntuu08p80#request-field-turnkeyturnKey | string | Optional | See meaning below. |
turnKey
Identifies the conversation turn this run served: the message_id of the opening user message. Messages produced by the run carry the same value as source_user_message_id.
To derive the corresponding evaluation trace ID, trim surrounding whitespace from the turn key and the event context's caller_key and correlation_id. Let conv_id be the trimmed caller key, falling back to the trimmed correlation ID when the caller key is empty. Compute SHA-256 over "trace|" + conv_id + "|msg:" + turn_key using the trimmed turn key and use the first 16 digest bytes, represented as 32 hexadecimal characters. The literal msg: is part of this derivation, not part of turn_key.
This identifies the trace when it has been ingested; the generation-completed event does not itself create an evaluation trace.
An empty key means no turn attribution, including turns recorded before this field was available or whose opening message could not be resolved. Do not invent a key for those turns.
Values of status
Section ID: DOC-API-MODEL-schema-pntuu08p80#request-values-status
Lifecycle state of a workflow execution, distinct from the reason a terminal execution ended.
| Value | No. | Form | Meaning |
|---|---|---|---|
WORKFLOW_STATUS_RUNNING | 0 | Canonical | The workflow has started and has not reached a terminal outcome. |
WORKFLOW_STATUS_COMPLETED | 1 | Canonical | The workflow finished successfully. |
WORKFLOW_STATUS_FAILED | 2 | Canonical | The workflow ended because execution failed; inspect its error or end reason. |
WORKFLOW_STATUS_TIMED_OUT | 3 | Canonical | The workflow ended because its execution time limit elapsed. |
WORKFLOW_STATUS_CANCELED | 4 | Canonical | The workflow was cancelled before normal completion. This enum retains its existing CANCELED wire spelling. |
In responses
Section ID: DOC-API-MODEL-schema-pntuu08p80#response
API JSON uses JSON field names (camelCase).
| Field | Type | Presence | Meaning |
|---|---|---|---|
Section ID: DOC-API-MODEL-schema-pntuu08p80#field-runidSection ID: DOC-API-MODEL-schema-pntuu08p80#response-field-runidrunId | string | Optional | Unique identifier for the workflow run |
Section ID: DOC-API-MODEL-schema-pntuu08p80#field-statusSection ID: DOC-API-MODEL-schema-pntuu08p80#response-field-statusstatus | string (WORKFLOW_STATUS_RUNNING, WORKFLOW_STATUS_COMPLETED, WORKFLOW_STATUS_FAILED, WORKFLOW_STATUS_TIMED_OUT, WORKFLOW_STATUS_CANCELED) or integer (int32) | Optional; explicit presence | Terminal status of the run |
Section ID: DOC-API-MODEL-schema-pntuu08p80#field-loopcountSection ID: DOC-API-MODEL-schema-pntuu08p80#response-field-loopcountloopCount | string (int64) | Optional | Number of agent loops/steps executed Pattern: ^-?\d+$. |
Section ID: DOC-API-MODEL-schema-pntuu08p80#field-durationmsSection ID: DOC-API-MODEL-schema-pntuu08p80#response-field-durationmsdurationMs | string (int64) | Optional | End-to-end run duration in milliseconds Pattern: ^-?\d+$. |
Section ID: DOC-API-MODEL-schema-pntuu08p80#field-usageSection ID: DOC-API-MODEL-schema-pntuu08p80#response-field-usageusage | Usage | Optional | Optional usage accounting for the run |
Section ID: DOC-API-MODEL-schema-pntuu08p80#field-errorSection ID: DOC-API-MODEL-schema-pntuu08p80#response-field-errorerror | RpcError | Optional | Structured error for FAILED/TIMED_OUT/CANCELED runs. |
Section ID: DOC-API-MODEL-schema-pntuu08p80#field-usagebymodelSection ID: DOC-API-MODEL-schema-pntuu08p80#response-field-usagebymodelusageByModel | Array of UsageByModel | Optional | Per-model breakdown of the same usage usage aggregates. Additive: usage stays the run-level total so existing consumers are unaffected, while billing keys its charges on model. Empty when the producer predates it. |
Section ID: DOC-API-MODEL-schema-pntuu08p80#field-turnkeySection ID: DOC-API-MODEL-schema-pntuu08p80#response-field-turnkeyturnKey | string | Optional | See meaning below. |
turnKey
Identifies the conversation turn this run served: the message_id of the opening user message. Messages produced by the run carry the same value as source_user_message_id.
To derive the corresponding evaluation trace ID, trim surrounding whitespace from the turn key and the event context's caller_key and correlation_id. Let conv_id be the trimmed caller key, falling back to the trimmed correlation ID when the caller key is empty. Compute SHA-256 over "trace|" + conv_id + "|msg:" + turn_key using the trimmed turn key and use the first 16 digest bytes, represented as 32 hexadecimal characters. The literal msg: is part of this derivation, not part of turn_key.
This identifies the trace when it has been ingested; the generation-completed event does not itself create an evaluation trace.
An empty key means no turn attribution, including turns recorded before this field was available or whose opening message could not be resolved. Do not invent a key for those turns.
Values of status
Section ID: DOC-API-MODEL-schema-pntuu08p80#response-values-status
Lifecycle state of a workflow execution, distinct from the reason a terminal execution ended.
| Value | No. | Form | Meaning |
|---|---|---|---|
WORKFLOW_STATUS_RUNNING | 0 | Canonical | The workflow has started and has not reached a terminal outcome. |
WORKFLOW_STATUS_COMPLETED | 1 | Canonical | The workflow finished successfully. |
WORKFLOW_STATUS_FAILED | 2 | Canonical | The workflow ended because execution failed; inspect its error or end reason. |
WORKFLOW_STATUS_TIMED_OUT | 3 | Canonical | The workflow ended because its execution time limit elapsed. |
WORKFLOW_STATUS_CANCELED | 4 | Canonical | The workflow was cancelled before normal completion. This enum retains its existing CANCELED wire spelling. |
Examples
Section ID: DOC-API-MODEL-schema-pntuu08p80#examples
event-llm-generation-completed
Section ID: DOC-API-MODEL-schema-pntuu08p80#example-event-llm-generation-completed
Illustrative payload, not a captured delivery. Identifiers, tool names and outcomes are examples; omitted fields depend on the event.
{
"runId": "9d4c2e1f-27b1-4304-ae54-af7fe876df31",
"status": "WORKFLOW_STATUS_COMPLETED",
"loopCount": 1,
"durationMs": "1250",
"usage": {
"promptTokens": 412,
"completionTokens": 88,
"totalTokens": 500
}
}
Download the public reference contract.
Document ID: DOC-API-MODEL-schema-pntuu08p80