Webhook status OK but output null? Read outcome: degraded

In a Sume run webhook, status: OK only means the run completed, not that you got structured output. When the run finished, billed you and produced real media in artifacts[] but could not project it into your output_schema, output is null, output_error says why, and the envelope's outcome is degraded.

That is the documented behavior in Run webhooks, read 2026-09-29. Branch on outcome instead of status when the question is whether you got usable output.

What do status and outcome each mean?

status is binary: OK when the run completed, ERROR when it failed. outcome has three values and adds the case in between.

Why would output be null on a completed run?

The docs give the usual cause: a schema that asks for a field the Format never produces. The run's media exists in artifacts[], but there is nothing to fill that field with, so the projection fails. A handler that reads only status keeps working; it just cannot tell ok from degraded.

How should the handler branch?

Switch on outcome. For ok, ship payload.output. For degraded, send the artifacts and the output_error to review. For error, retry or alert using payload.error, falling back to the envelope's error.

switch (event.outcome) {
  case "ok":
    return ship(event.payload.output);
  case "degraded":
    return reviewManually(event.payload.artifacts, event.payload.output_error);
  case "error":
    return retryOrAlert(event.payload?.error ?? event.error);
}

Is this the same as an invalid output schema?

No. A schema outside the strict subset is rejected before any run starts with output_schema_invalid, and nothing is billed. degraded is a schema that was accepted but could not be satisfied after the work was done. See fix output_schema_invalid violations for the up-front case, and GET /v1/usage for the authoritative billing record.

Will polling show the same thing?

Yes. The webhook payload is byte-identical to the data object of GET /v1/{family}-runs/{run_id} for the same run; the poll response wraps it in { "data": ... } and the webhook does not. It is built by the same code path, so one handler can serve both transports.

That also means a degraded run is not a delivery glitch: fetching the receipt again will not conjure the missing output. Fix the schema or the Format, then start a new run.

What does it cost when a run is degraded?

The run billed you: the docs describe a run that can complete, bill you and produce real media. The receipt's usage.billable_amount_usd_micros carries the generation spend attributed to the run, usage is null when that could not be read, and GET /v1/usage stays the authoritative billing record.