> ## Documentation Index
> Fetch the complete documentation index at: https://www.stratus.run/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Rollout (Multi-Step Prediction)

> Predict multi-step action sequences and validate plans before execution

## Overview

The `/v1/rollout` endpoint provides **multi-step action prediction** - a crystal ball for web automation. Predict what will happen through a sequence of actions without executing them.

<Info>
  **Think of it as:** Simulating the future before you commit to it.
</Info>

## Use Cases

<CardGroup cols={2}>
  <Card title="Plan Validation" icon="check">
    Test if an action sequence will achieve your goal
  </Card>

  <Card title="Path Comparison" icon="code-compare">
    Compare multiple sequences to find the optimal one
  </Card>

  <Card title="Debugging" icon="bug">
    Understand why an action sequence failed
  </Card>

  <Card title="Goal Estimation" icon="bullseye">
    Determine minimum steps needed for a goal
  </Card>
</CardGroup>

## Request Modes

### Goal-Based Planning

Let Stratus plan the action sequence for you:

```json theme={null}
{
  "goal": "Find and book a hotel in San Francisco",
  "max_steps": 3,
  "return_intermediate": true
}
```

### Explicit Action Sequence

Test a specific sequence you provide:

```json theme={null}
{
  "goal": "Navigate and interact with webpage",
  "actions": [17, 10, 28],
  "return_intermediate": true
}
```

## Parameters

<ParamField body="goal" type="string" required>
  Natural language description of what you want to achieve
</ParamField>

<ParamField body="max_steps" type="integer" default={5}>
  Maximum number of steps to plan (1-10 recommended)
</ParamField>

<ParamField body="actions" type="integer[]">
  Explicit action IDs to execute (0-66). If provided, overrides planning.
</ParamField>

<ParamField body="return_intermediate" type="boolean" default={true}>
  Include intermediate state predictions. **Note:** Must be `true` (known bug with `false`)
</ParamField>

<ParamField body="initial_state" type="string">
  Custom initial state description (optional)
</ParamField>

<ParamField body="mode" type="string">
  Execution mode for the rollout (optional)
</ParamField>

## Response

```json theme={null}
{
  "id": "stratus-rollout-95e45106220c",
  "object": "rollout.prediction",
  "created": 1769575678,
  "goal": "Find and book a hotel in San Francisco",
  "initial_state": "Goal: Find and book a hotel in San Francisco\nStep: 1",

  "action_sequence": [
    {
      "step": 1,
      "action_id": 17,
      "action_name": "search",
      "action_category": "retrieval"
    },
    {
      "step": 2,
      "action_id": 10,
      "action_name": "select",
      "action_category": "navigation"
    },
    {
      "step": 3,
      "action_id": 28,
      "action_name": "read",
      "action_category": "retrieval"
    }
  ],

  "predictions": [
    {
      "step": 1,
      "action": {
        "step": 1,
        "action_id": 17,
        "action_name": "search",
        "action_category": "retrieval"
      },
      "current_state": {
        "step": 0,
        "magnitude": 16.37,
        "confidence": "High"
      },
      "predicted_state": {
        "step": 1,
        "magnitude": 18.39,
        "confidence": "High"
      },
      "state_change": 15.48,
      "interpretation": "Significant state transition (action has strong effect)"
    }
    // ... more predictions
  ],

  "summary": {
    "total_steps": 3,
    "initial_magnitude": 16.37,
    "final_magnitude": 21.63,
    "total_state_change": 23.45,
    "outcome": "Goal likely achieved (large cumulative change)",
    "action_path": ["search", "select", "read"]
  }
}
```

## Understanding Results

### State Magnitude

The `magnitude` field indicates state complexity:

| Range | Meaning                             |
| ----- | ----------------------------------- |
| \< 10 | Low complexity                      |
| 10-15 | Medium complexity                   |
| 15-20 | High complexity (typical web tasks) |
| > 20  | Very high complexity                |

### State Change

The `state_change` field shows transition significance:

| Range | Meaning                            |
| ----- | ---------------------------------- |
| \< 5  | Minor transition                   |
| 5-10  | Moderate transition                |
| 10-15 | Significant transition             |
| > 15  | Major transition (critical action) |

<Tip>
  **Pro tip:** Actions with state change >15 are usually the most important steps in your sequence.
</Tip>

### Outcome Interpretation

The `outcome` field predicts goal achievement:

* **"Goal likely achieved"** - Total state change >20, strong prediction
* **"Significant progress"** - Total state change 10-20, moderate progress
* **"Minimal progress"** - Total state change \<10, weak prediction

## Examples

### Validate a Plan

<CodeGroup>
  ```python Python theme={null}
  import requests

  API_URL = "https://api.stratus.run"
  API_KEY = "stratus_sk_live_your_key"

  response = requests.post(
      f"{API_URL}/v1/rollout",
      headers={
          "Authorization": f"Bearer {API_KEY}",
          "Content-Type": "application/json"
      },
      json={
          "goal": "Login to website and download report",
          "max_steps": 5
      }
  )

  result = response.json()
  outcome = result['summary']['outcome']

  if "Goal likely achieved" in outcome:
      print("✅ Plan validated!")
      execute_plan(result['summary']['action_path'])
  else:
      print("⚠️ Plan may fail - revising")
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.stratus.run/v1/rollout', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.STRATUS_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      goal: 'Login to website and download report',
      max_steps: 5
    })
  });

  const result = await response.json();
  const outcome = result.summary.outcome;

  if (outcome.includes('Goal likely achieved')) {
    console.log('✅ Plan validated!');
    executePlan(result.summary.action_path);
  } else {
    console.log('⚠️ Plan may fail - revising');
  }
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.stratus.run/v1/rollout \
    -H "Authorization: Bearer stratus_sk_live_your_key" \
    -H "Content-Type: application/json" \
    -d '{
      "goal": "Login to website and download report",
      "max_steps": 5
    }' | jq '.summary'
  ```
</CodeGroup>

### Compare Action Sequences

```python theme={null}
def find_best_path(goal, path_options):
    results = []

    for actions in path_options:
        response = requests.post(
            f"{API_URL}/v1/rollout",
            headers={"Authorization": f"Bearer {API_KEY}"},
            json={"goal": goal, "actions": actions}
        )

        result = response.json()
        results.append({
            'actions': actions,
            'score': result['summary']['total_state_change'],
            'outcome': result['summary']['outcome']
        })

    best = max(results, key=lambda x: x['score'])
    return best

# Test different paths
paths = [
    [17, 10, 28],  # search → select → read
    [5, 10, 28],   # navigate → select → read
    [17, 28, 10]   # search → read → select
]

best_path = find_best_path("Book hotel", paths)
print(f"Best sequence: {best_path['actions']}")
print(f"Score: {best_path['score']:.2f}")
```

### Estimate Steps Needed

```python theme={null}
def estimate_minimum_steps(goal):
    for steps in [2, 3, 5, 7, 10]:
        response = requests.post(
            f"{API_URL}/v1/rollout",
            headers={"Authorization": f"Bearer {API_KEY}"},
            json={"goal": goal, "max_steps": steps}
        )

        result = response.json()
        outcome = result['summary']['outcome']

        print(f"{steps} steps: {outcome}")

        if "Goal likely achieved" in outcome:
            return steps, result['summary']['action_path']

    return None, None

# Usage
min_steps, path = estimate_minimum_steps("Complete checkout flow")
if min_steps:
    print(f"✅ Minimum {min_steps} steps: {path}")
```

## Performance

| Metric         | Value                           |
| -------------- | ------------------------------- |
| **Latency**    | 2-5s for 3-5 steps              |
| **Throughput** | \~0.5 req/s                     |
| **Max Steps**  | 10+ (scales linearly)           |
| **Model**      | stratus-v3-base (290.4M params) |

<Note>
  Latency increases linearly with `max_steps`. For best performance, use 3-5 steps.
</Note>

## Action Categories

Actions are categorized by their purpose:

| Category        | Examples                | Typical Use              |
| --------------- | ----------------------- | ------------------------ |
| **retrieval**   | search, read, extract   | Getting information      |
| **navigation**  | select, click, navigate | Moving through interface |
| **interaction** | type, submit, scroll    | Modifying state          |
| **system**      | pad, unk, start         | Special tokens           |

## Known Limitations

<Warning>
  **Known Bug:** Setting `return_intermediate: false` causes a server error. Always use `true`.
</Warning>

Additional limitations:

* 903 discrete actions (action IDs 0-902)
* State embeddings not human-readable (use magnitude/change as proxies)
* Planning quality depends on goal clarity

## Troubleshooting

### "500 Internal Server Error"

Check if `return_intermediate` is set to `false`. Change to `true`.

### Unexpected Action Sequence

Make your goal more specific:

```json theme={null}
// ❌ Vague
{"goal": "do the thing"}

// ✅ Specific
{"goal": "Search for hotels, select top result, and view details"}
```

### Slow Response (>10s)

Reduce `max_steps`:

```json theme={null}
{"goal": "...", "max_steps": 3}  // Instead of 10
```

## Real-World Example

Here's a complete example from production testing:

```json theme={null}
// Request
{
  "goal": "Find and book a hotel in San Francisco",
  "max_steps": 3,
  "return_intermediate": true
}

// Response Summary
{
  "action_path": ["search", "select", "read"],
  "outcome": "Goal likely achieved (large cumulative change)",
  "total_steps": 3,
  "total_state_change": 23.45,
  "initial_magnitude": 16.37,
  "final_magnitude": 21.63
}
```

**Analysis:**

* ✅ Logical sequence: search → select result → read details
* ✅ High confidence (all states >15 magnitude)
* ✅ Strong transitions (15.48, 11.10, 18.95)
* ✅ Goal achievement predicted (23.45 total change)
* ⏱️ Response time: \~2.5s

## What's Next?

* **Phase 2:** Policy head for better action selection (Feb-Mar 2026)
* **Phase 3:** Generative adapter to translate embeddings → text (Mar-Apr 2026)
* **Phase 4:** Continuous action space for precise control (Apr-May 2026)

<Card title="Need Help?" icon="question" href="/docs/concepts/use-cases">
  See more examples and use cases in our concepts guide
</Card>