RunEventsPage

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/edgaze-ai/json-schema/edgaze-ai-run-events-page-schema.json",
  "title": "RunEventsPage",
  "description": "Response body for GET /runs/{id}/events.",
  "x-generated": "2026-11-06",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/edgaze-ai-openapi.json#/components/schemas/RunEventsPage",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "minLength": 1,
      "format": "uuid"
    },
    "events": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/RunEvent"
      }
    },
    "hasMore": {
      "type": "boolean"
    },
    "nextAfterSequence": {
      "anyOf": [
        {
          "type": "integer",
          "minimum": 0
        },
        {
          "type": "null"
        }
      ],
      "description": "Pass as `afterSequence` to fetch the next page. `null` when `hasMore` is false."
    }
  },
  "required": [
    "id",
    "events",
    "hasMore",
    "nextAfterSequence"
  ],
  "additionalProperties": false,
  "$defs": {
    "PublicRunStatus": {
      "type": "string",
      "enum": [
        "pending",
        "running",
        "suspended",
        "completed",
        "failed",
        "cancelled"
      ],
      "description": "Canonical run status exposed by the public API."
    },
    "RunEvent": {
      "type": "object",
      "properties": {
        "type": {
          "anyOf": [
            {
              "type": "string",
              "enum": [
                "run.queued",
                "run.queue_position",
                "run.preparing",
                "run.started",
                "run.suspended",
                "run.resumed",
                "run.completed",
                "run.failed",
                "run.cancelled",
                "node.started",
                "node.output.delta",
                "node.completed",
                "node.failed",
                "node.retry_scheduled",
                "node.skipped"
              ]
            },
            {
              "type": "string"
            }
          ],
          "description": "Event name. The listed values are every type emitted today; branch on them. The union stays open to plain strings on purpose, because adding an event type is not a breaking change: ignore values you do not recognize instead of failing."
        },
        "sequence": {
          "type": "integer",
          "minimum": 0,
          "description": "Monotonic, gap-free position in this run's log. Use as the `afterSequence` cursor and to order events."
        },
        "ts": {
          "type": "string",
          "format": "date-time"
        },
        "nodeId": {
          "description": "Workflow node this event belongs to, or `null` for run-level events.",
          "type": [
            "string",
            "null"
          ]
        },
        "attempt": {
          "anyOf": [
            {
              "type": "integer",
              "minimum": 1
            },
            {
              "type": "null"
            }
          ],
          "description": "1-based execution attempt for node events; `null` for run-level events."
        },
        "data": {
          "anyOf": [
            {
              "$ref": "#/$defs/RunEventData"
            },
            {
              "type": "null"
            }
          ],
          "description": "Event-specific content, or `null` when this event type carries none."
        }
      },
      "required": [
        "type",
        "sequence",
        "ts",
        "nodeId",
        "attempt",
        "data"
      ],
      "additionalProperties": false,
      "description": "One row in the durable run event log."
    },
    "RunEventData": {
      "type": "object",
      "properties": {
        "text": {
          "description": "Incremental output text. Present on `node.output.delta`; concatenate in `sequence` order to reconstruct a node's streamed output.",
          "type": "string"
        },
        "status": {
          "description": "Run status implied by this event. Present on run lifecycle events.",
          "$ref": "#/$defs/PublicRunStatus"
        },
        "reason": {
          "description": "Why the run failed, suspended, or a node was skipped. Sanitized to the same buyer-safe text as `Run.reason`.",
          "type": [
            "string",
            "null"
          ]
        },
        "queue": {
          "description": "Present on `run.queue_position`: the run is waiting for capacity (`state: waiting`, its place in line and an estimated wait) or has just left the line (`state: starting`, position 0).",
          "$ref": "#/$defs/RunQueue"
        }
      },
      "additionalProperties": false,
      "description": "Event-specific content, projected to the fields that are safe for the caller."
    },
    "RunQueue": {
      "type": "object",
      "properties": {
        "state": {
          "type": "string",
          "enum": [
            "waiting",
            "starting"
          ],
          "description": "`waiting`: in line for capacity. `starting`: it just left the line and is being started."
        },
        "position": {
          "type": "integer",
          "minimum": 0,
          "description": "Place in line, 1 = next. 0 while starting."
        },
        "etaSeconds": {
          "anyOf": [
            {
              "type": "integer",
              "minimum": 1
            },
            {
              "type": "null"
            }
          ],
          "description": "Estimated seconds until it starts, or null when unknown."
        }
      },
      "required": [
        "state",
        "position",
        "etaSeconds"
      ],
      "additionalProperties": false,
      "description": "Edgaze starts runs immediately while it has capacity. At full capacity a run waits in line and starts automatically, in order; nothing is needed from the caller and nothing is charged for waiting. A run that waits past its limit fails with a reason and is not charged."
    }
  }
}