> ## Documentation Index
> Fetch the complete documentation index at: https://aidocs.ethanbragdon.icu/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```text theme={null}
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:

```text theme={null}
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.

<Card title="Webhooks" icon="webhook" href="/developers/webhooks">
  Receive signed asynchronous completion and failure events from long-running work.
</Card>