{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/edgaze-ai/json-schema/edgaze-ai-run-schema.json",
  "title": "Run",
  "description": "Response body for GET /runs/{id}.",
  "x-generated": "2026-11-06",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/edgaze-ai-openapi.json#/components/schemas/Run",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "minLength": 1,
      "format": "uuid"
    },
    "status": {
      "$ref": "#/$defs/PublicRunStatus"
    },
    "reason": {
      "description": "Buyer-safe failure explanation. Non-null only when `status` is `failed`; provider-specific detail is deliberately generalized.",
      "type": [
        "string",
        "null"
      ]
    },
    "suspended": {
      "type": "boolean",
      "description": "True exactly when `status` is `suspended`; kept as a separate flag so a caller can test for 'waiting' without matching on the status enum. A run suspends for one of two reasons, reported as `reason` on the `run.suspended` event: `wait_timer` (a delay node) resumes itself when the timer fires, while `wait_signal` (the workflow needs credentials) waits for the buyer to supply them on the web run page. The API cannot resume a run; POST /runs/{id}/cancel is the only way for an API caller to end one early."
    },
    "workflowId": {
      "anyOf": [
        {
          "type": "string",
          "minLength": 1,
          "format": "uuid"
        },
        {
          "type": "null"
        }
      ]
    },
    "workflowVersionId": {
      "anyOf": [
        {
          "type": "string",
          "minLength": 1,
          "format": "uuid"
        },
        {
          "type": "null"
        }
      ]
    },
    "startedAt": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time"
        },
        {
          "type": "null"
        }
      ]
    },
    "completedAt": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time"
        },
        {
          "type": "null"
        }
      ]
    },
    "displayedChargeUsd": {
      "description": "Buyer-facing charge. `null` until the run settles. USD amount as a JSON number with up to six decimal places. Preserve the documented precision and do not round intermediate calculations to two decimal places.",
      "type": [
        "number",
        "null"
      ]
    },
    "billingStatus": {
      "$ref": "#/$defs/BillingStatus"
    },
    "outcome": {
      "$ref": "#/$defs/RunOutcome"
    },
    "queue": {
      "anyOf": [
        {
          "$ref": "#/$defs/RunQueue"
        },
        {
          "type": "null"
        }
      ],
      "description": "Non-null while the run is `pending` because it is waiting for capacity; null otherwise."
    },
    "outputs": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/RunOutputField"
      }
    }
  },
  "required": [
    "id",
    "status",
    "reason",
    "suspended",
    "workflowId",
    "workflowVersionId",
    "startedAt",
    "completedAt",
    "displayedChargeUsd",
    "billingStatus",
    "outcome",
    "queue",
    "outputs"
  ],
  "additionalProperties": false,
  "$defs": {
    "BillingStatus": {
      "type": "string",
      "enum": [
        "pending",
        "settled",
        "not_charged"
      ],
      "description": "Whether the buyer-facing charge for this run is still pending, finalized, or not applicable."
    },
    "PublicRunStatus": {
      "type": "string",
      "enum": [
        "pending",
        "running",
        "suspended",
        "completed",
        "failed",
        "cancelled"
      ],
      "description": "Canonical run status exposed by the public API."
    },
    "RunOutcome": {
      "anyOf": [
        {
          "type": "string",
          "enum": [
            "completed",
            "completed_with_issues"
          ]
        },
        {
          "type": "null"
        }
      ],
      "description": "Set when `status` is `completed`, null otherwise. `completed`: every step finished. `completed_with_issues`: the run returned its outputs but some steps failed; it is charged for the completed steps' compute only, without the creator's price."
    },
    "RunOutputField": {
      "type": "object",
      "properties": {
        "nodeId": {
          "type": "string"
        },
        "name": {
          "type": "string"
        },
        "type": {
          "type": "string"
        },
        "value": {}
      },
      "required": [
        "nodeId",
        "name",
        "type",
        "value"
      ],
      "additionalProperties": {},
      "description": "One output produced by the workflow."
    },
    "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."
    }
  }
}