# Events (/docs/api/events)

Every customer SSE event type, its payload, and terminal semantics.



The [stream](/docs/api/streaming) emits four event types with a common
envelope.

| `event_type` | Meaning                 | Terminal |
| ------------ | ----------------------- | -------- |
| `stage`      | Progress advanced.      | No       |
| `partial`    | Incremental result.     | No       |
| `completed`  | Job done; final result. | Yes      |
| `failed`     | Job failed; error code. | Yes      |

Common fields:

<TypeTable
  type="{
  event_type: { description: &#x22;stage | partial | completed | failed.&#x22;, type: &#x22;string&#x22; },
  job_id: { description: &#x22;The job id.&#x22;, type: &#x22;string&#x22; },
  stage: { description: &#x22;Opaque progress label. Do not branch on its value.&#x22;, type: &#x22;string | null&#x22; },
  message: { description: &#x22;Human-readable progress.&#x22;, type: &#x22;string&#x22; },
  timestamp: { description: &#x22;ISO 8601 timestamp.&#x22;, type: &#x22;string&#x22; },
}"
/>

## stage [#stage]

Drive a progress indicator from `message`; treat `stage` as opaque.

```
event: stage
id: 2
data: {"event_type":"stage","job_id":"b7c1...","stage":"…","message":"Pricing in progress…","timestamp":"2026-05-15T12:00:02Z"}
```

## partial [#partial]

`result` is a subset of the final `JobResult`.

```
event: partial
id: 5
data: {"event_type":"partial","job_id":"b7c1...","stage":"…","message":"...","timestamp":"2026-05-15T12:00:05Z","result":{...}}
```

## completed [#completed]

Terminal. `result` carries the full `JobResult` (`product_profile`,
`fused_distribution`, `scenario_forecast`, …).

```
event: completed
id: 9
data: {"event_type":"completed","job_id":"b7c1...","stage":"…","message":"...","timestamp":"2026-05-15T12:00:42Z","result":{"product_profile":{...},"fused_distribution":{"quantiles":{"0.5":812.0},"currency":"USD"},"scenario_forecast":null}}
```

## failed [#failed]

Terminal. `code` is a public [error code](/docs/api/errors).

```
event: failed
id: 4
data: {"event_type":"failed","job_id":"b7c1...","stage":null,"message":"Not enough comparable listings to price this item.","timestamp":"2026-05-15T12:00:11Z","code":"insufficient_data"}
```

<Callout type="info" title="Terminal closes the stream">
  After `completed` or `failed`, the server closes the connection. Do not
  reconnect.
</Callout>