Event catalog

Every event shares the same envelope; data varies by event type.

Envelope

Name
id
Type
string
Description
Event id (evt_...). Stable across retries and replays of the same event — use it for deduplication.
Name
type
Type
string
Description
The event type, e.g. automation.run.completed.
Name
createdAt
Type
string
Description
ISO 8601 timestamp of when the event was created.
Name
data
Type
object
Description
Event-specific payload, documented per event below.

automation.run.completed

An automation-triggered agent run finished successfully.

Name
agentId
Type
string
Description
Id of the agent run.
Name
title
Type
string | null
Description
Run title, when one was set.
Name
status
Type
string
Description
Always completed for this event.
Name
summary
Type
string | null
Description
Short text summary of what the run did, found, or changed. Falls back to truncated final-message text when summary generation is unavailable.
Name
imageUrl
Type
string | null
Description
Reserved for a public URL of the last image the run produced. Currently always null; treat any future non-null value as optional enrichment.
Name
chatUrl
Type
string
Description
Permalink to the chat in the Vuon app.
Name
automationKey
Type
string
Description
Key of the automation that triggered the run.
Name
triggerRuleId
Type
string | null
Description
Id of the trigger rule that started the run, when applicable.
Name
completedAt
Type
string
Description
ISO 8601 timestamp of when the run reached its terminal status.
Name
failureReason
Type
null
Description
Always null for completed runs.

Sample payload

{
  "id": "evt_5c9b2f4a1e8d3b6a0f7c4d2e9a",
  "type": "automation.run.completed",
  "createdAt": "2026-07-10T14:22:31.000Z",
  "data": {
    "agentId": "4f6f8f2a-1b6e-4c7e-9c2d-8f3a5b1c9d0e",
    "title": "Daily revenue digest",
    "status": "completed",
    "summary": "Revenue for July 9 was $128,450, up 4.2% day-over-day. Top mover: enterprise plan upgrades (+$9,800).",
    "imageUrl": null,
    "chatUrl": "https://acme.vuon.ai/chat/a-4f6f8f2a-1b6e-4c7e-9c2d-8f3a5b1c9d0e",
    "automationKey": "daily-revenue-digest",
    "triggerRuleId": "trig_rule_01H9X4Z8QK",
    "completedAt": "2026-07-10T14:22:31.000Z",
    "failureReason": null
  }
}

automation.run.failed

An automation-triggered agent run failed or was stopped before completing. The data object has the same shape as automation.run.completed, with these differences:

status is failed or stopped.
failureReason carries a human-readable description of what went wrong (may be null for stopped runs).
summary and imageUrl are always null.

Sample payload

{
  "id": "evt_9a1d4c7e2b5f8a3c6d0e9b4f7c",
  "type": "automation.run.failed",
  "createdAt": "2026-07-10T14:22:31.000Z",
  "data": {
    "agentId": "4f6f8f2a-1b6e-4c7e-9c2d-8f3a5b1c9d0e",
    "title": "Daily revenue digest",
    "status": "failed",
    "summary": null,
    "imageUrl": null,
    "chatUrl": "https://acme.vuon.ai/chat/a-4f6f8f2a-1b6e-4c7e-9c2d-8f3a5b1c9d0e",
    "automationKey": "daily-revenue-digest",
    "triggerRuleId": "trig_rule_01H9X4Z8QK",
    "completedAt": "2026-07-10T14:22:31.000Z",
    "failureReason": "Warehouse query timed out after 3 attempts"
  }
}

New event types may be added over time. Ignore event types you don't recognize instead of failing — endpoints subscribed to "all events" receive new types automatically.