Rollout (Multi-Step Prediction)

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.

Think of it as: Simulating the future before you commit to it.

Use Cases

Plan Validation

Test if an action sequence will achieve your goal

Path Comparison

Compare multiple sequences to find the optimal one

Debugging

Understand why an action sequence failed

Goal Estimation

Determine minimum steps needed for a goal

Request Modes

Goal-Based Planning

Let Stratus plan the action sequence for you:

{
  "goal": "Find and book a hotel in San Francisco",
  "max_steps": 3,
  "return_intermediate": true
}

Explicit Action Sequence

Test a specific sequence you provide:

{
  "goal": "Navigate and interact with webpage",
  "actions": [17, 10, 28],
  "return_intermediate": true
}

Parameters

string

required

Natural language description of what you want to achieve

integer

default:5

Maximum number of steps to plan (1-10 recommended)

integer[]

Explicit action IDs to execute (0-66). If provided, overrides planning.

boolean

default:true

Include intermediate state predictions. Note: Must be true (known bug with false)

string

Custom initial state description (optional)

string

Execution mode for the rollout (optional)

Response

{
  "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)

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

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

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")

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');
}

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'

Compare Action Sequences

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

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)

Latency increases linearly with max_steps. For best performance, use 3-5 steps.

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

Known Bug: Setting return_intermediate: false causes a server error. Always use true.

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:

// ❌ Vague
{"goal": "do the thing"}

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

Slow Response (>10s)

Reduce max_steps:

{"goal": "...", "max_steps": 3}  // Instead of 10

Real-World Example

Here’s a complete example from production testing:

// 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)

Need Help?

See more examples and use cases in our concepts guide

​Overview

​Use Cases

Plan Validation

Path Comparison

Debugging

Goal Estimation

​Request Modes

​Goal-Based Planning

​Explicit Action Sequence

​Parameters

​Response

​Understanding Results

​State Magnitude

​State Change

​Outcome Interpretation

​Examples

​Validate a Plan

​Compare Action Sequences

​Estimate Steps Needed

​Performance

​Action Categories

​Known Limitations

​Troubleshooting

​”500 Internal Server Error”

​Unexpected Action Sequence

​Slow Response (>10s)

​Real-World Example

​What’s Next?

Need Help?

Overview

Use Cases

Request Modes

Goal-Based Planning

Explicit Action Sequence

Parameters

Response

Understanding Results

State Magnitude

State Change

Outcome Interpretation

Examples

Validate a Plan

Compare Action Sequences

Estimate Steps Needed

Performance

Action Categories

Known Limitations

Troubleshooting

”500 Internal Server Error”

Unexpected Action Sequence

Slow Response (>10s)

Real-World Example

What’s Next?