Responses & Runs

Understand Starfire-native responses, long-running runs, cancellation, status, and event streaming concepts.

Responses & runs

Starfire’s native Developer Platform separates short interactive generation from long-running work.

Responses

A response is the native generation abstraction for Starfire-specific capabilities that do not fit cleanly into a compatibility endpoint.

A response can carry concepts such as:

• model
• input
• reasoning mode
• tools
• project or organization context
• structured output requirements
• streaming preference

The exact request schema remains subject to the active Alpha API contract.

Runs

A run represents work that can outlive one HTTP request.

Typical candidates include:

• Deep Research
• FORGE builds
• long analysis
• future agent or workflow execution

A run model lets the client start work, receive an identifier, check status later, cancel when allowed, and consume progress events.

Lifecycle

create run
   ↓
queued
   ↓
running
   ↓
completed / failed / cancelled

A richer workflow can expose intermediate stages without forcing the client to keep one network connection open for the entire job.

Event streaming

The Developer Platform architecture uses server-sent event concepts for live progress where appropriate.

Generation-style events can include concepts such as:

response.started
response.delta
response.completed

A FORGE run can expose more specific stage events such as planning, file creation, validation, repair, packaging, and completion.

Cancellation

Cancellation is best-effort and state-dependent. A completed run cannot meaningfully be cancelled, and a workflow may have already committed an external side effect before a later cancellation request arrives.

Clients should always inspect the final run state.

Webhooks vs streaming

Use streaming when a client is actively waiting for progress.

Use webhooks when your backend should be notified after an asynchronous run changes state even if no user is connected at that moment.

Metering

A long-running run can make multiple model and tool calls. Usage should be attributed to the owning account or organization and visible in the developer usage surfaces.

Webhooks

Receive signed asynchronous completion and failure events from long-running work.