Trajectory Generation (Rollout)

Overview

Rollout generation creates model responses (trajectories) for each stimulus generated by a stim job. Rollout output is used as training data for bakes.

Endpoints

Run Rollout Job

Start a rollout job for the target. Endpoint: POST /v1/repo/{repo_name}/targets/{target_name}/rollout Request:

curl -X POST "https://bapi.bread.com.ai/v1/repo/my_repo/targets/coding_target/rollout" \
  -H "Authorization: Bearer $BREAD_API_KEY"

target_name

string

required

Target name

repo_name

string

required

Repository name

Prerequisites:

Completed stim job (stim output must exist)
Target must have model_name configured

Verify stim job is complete before running rollout

Behavior:

Creates job marker and returns immediately
Job executes asynchronously in background
Idempotent: repeated calls return current state

SDK Usage:

# Python: repo_name must be a keyword argument
client.targets.rollout.run(target_name="coding_target", repo_name="my_repo")

# With polling (default poll=True)
client.targets.rollout.run(target_name="coding_target", repo_name="my_repo", poll=True)

Python SDK: The repo_name parameter must be passed as a keyword argument (not positional). This is intentional for API clarity and consistency.Polling: By default, poll=True automatically waits for the job to complete. Manual polling loops are no longer needed unless you set poll=False.

Response: 200 OK

{
  "status": "running",
  "lines": 0,
  "parameters": {}
}

Response Fields:

status: string - Job status ('not_started', 'running', 'complete', or 'failed')
lines: number - Number of trajectories generated
parameters: object - Job configuration

Get Rollout Status

Get rollout job status. Endpoint: GET /v1/repo/{repo_name}/targets/{target_name}/rollout Request:

curl -X GET "https://bapi.bread.com.ai/v1/repo/my_repo/targets/coding_target/rollout" \
  -H "Authorization: Bearer $BREAD_API_KEY"

target_name

string

required

Target name

repo_name

string

required

Repository name

Response: 200 OK

{
  "status": "complete",
  "lines": 500,
  "parameters": {}
}

Response Fields:

status: string - 'not_started', 'running', 'complete', or 'failed'
lines: number - Number of generated trajectories
parameters: object - Job configuration

Get Rollout Output

Get paginated rollout output data. Endpoint: GET /v1/repo/{repo_name}/targets/{target_name}/rollout/output Request:

curl -X GET "https://bapi.bread.com.ai/v1/repo/my_repo/targets/coding_target/rollout/output?limit=100&offset=0" \
  -H "Authorization: Bearer $BREAD_API_KEY"

target_name

string

required

Target name

repo_name

string

required

Repository name

limit

integer

Number of lines to return (max 1000)

offset

integer

Starting line number (0-indexed)

Response: 200 OK

{
  "status": "complete",
  "lines": 500,
  "offset": 0,
  "limit": 100,
  "has_more": true,
  "output": [
    {
      "stimulus": "Write a function to reverse a string",
      "response": "def reverse_string(s):\n    return s[::-1]",
      "model": "Qwen/Qwen3-32B"
    },
    "..."
  ],
  "parameters": {}
}

Response Fields:

status: string - Job status
lines: number - Total number of trajectories
offset: number - Starting offset
limit: number - Page size
has_more: boolean - Whether more data available
output: Array<object> - List of generated trajectories
parameters: object - Rollout configuration

Complete Workflow Example

Verify Stim Complete

# Check stim status
stim_response=$(curl -s -X GET "https://bapi.bread.com.ai/v1/repo/my_repo/targets/coding_target/stim" \
  -H "Authorization: Bearer $BREAD_API_KEY")

stim_status=$(echo "$stim_response" | jq -r '.status')

if [ "$stim_status" != "complete" ]; then
  echo "Stim job must complete before rollout"
  exit 1
fi

stim_lines=$(echo "$stim_response" | jq -r '.lines')
echo "Stim complete with $stim_lines stimuli"

Start Rollout Job

curl -X POST "https://bapi.bread.com.ai/v1/repo/my_repo/targets/coding_target/rollout" \
  -H "Authorization: Bearer $BREAD_API_KEY"

Poll Status

# Poll status every 10 seconds (rollout takes longer)
while true; do
  response=$(curl -s -X GET "https://bapi.bread.com.ai/v1/repo/my_repo/targets/coding_target/rollout" \
    -H "Authorization: Bearer $BREAD_API_KEY")
  
  status=$(echo "$response" | jq -r '.status')
  lines=$(echo "$response" | jq -r '.lines')
  
  if [ "$status" = "complete" ]; then
    echo "Complete! Generated $lines trajectories"
    break
  fi
  
  echo "Status: $status, Lines: $lines"
  sleep 10
done

Fetch Output

curl -X GET "https://bapi.bread.com.ai/v1/repo/my_repo/targets/coding_target/rollout/output?limit=100" \
  -H "Authorization: Bearer $BREAD_API_KEY"

Pagination Example

Fetch all rollout output:

#!/bin/bash

# Fetch all rollout output
offset=0
limit=1000
all_output=()

while true; do
  response=$(curl -s -X GET "https://bapi.bread.com.ai/v1/repo/my_repo/targets/coding_target/rollout/output?limit=$limit&offset=$offset" \
    -H "Authorization: Bearer $BREAD_API_KEY")
  
  # Extract output array
  output=$(echo "$response" | jq -r '.output[]')
  has_more=$(echo "$response" | jq -r '.has_more')
  
  # Process output
  while IFS= read -r line; do
    all_output+=("$line")
  done <<< "$output"
  
  count=${#all_output[@]}
  echo "Fetched $count trajectories..."
  
  if [ "$has_more" = "false" ]; then
    break
  fi
  
  offset=$((offset + limit))
done

echo "Total trajectories: ${#all_output[@]}"

Understanding Trajectories

A trajectory represents the model’s complete response to a stimulus:

{
  "stimulus": "Write a function to reverse a string",
  "response": "def reverse_string(s):\n    return s[::-1]",
  "model": "Qwen/Qwen3-32B",
  "temperature": 1.0,
  "tokens": 25
}

Multiple Trajectories Per Stimulus

Configure multiple responses per stimulus in target configuration:

curl -X POST "https://bapi.bread.com.ai/v1/repo/my_repo/targets" \
  -H "Authorization: Bearer $BREAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "target_name": "multi_traj_target",
    "template": "default",
    "overrides": {
      "model_name": "Qwen/Qwen3-32B",
      "num_traj_per_stimulus": 5,
      "temperature": 1.0
    }
  }'

Multiple trajectories per stimulus provide diverse training data and can improve model robustness.

Best Practices

Verify Prerequisites

Always check that stim job is complete and model_name is configured before running rollout

Poll Less Frequently

Rollout jobs can take longer than stim. Poll every 10-30 seconds instead of every 5 seconds

Monitor Progress

Check the lines field during polling to see generation progress

Handle Timeouts

For large rollouts, configure appropriate timeout values on the client

Error Handling

Not Found (404)

Target doesn’t exist:

curl -X POST "https://bapi.bread.com.ai/v1/repo/my_repo/targets/nonexistent/rollout" \
  -H "Authorization: Bearer $BREAD_API_KEY"

Response: 404 Not Found

{
  "error": "Target not found"
}

Missing Prerequisites (400)

Stim job not complete or model_name not configured: Response: 400 Bad Request

{
  "error": "Stim job must complete before running rollout"
}

{
  "error": "model_name must be configured in target"
}

API Reference

API Playground

Overview

Endpoints

Run Rollout Job

Get Rollout Status

Get Rollout Output

Complete Workflow Example

Understanding Trajectories

Multiple Trajectories Per Stimulus

Best Practices

Error Handling

Not Found (404)

Missing Prerequisites (400)

Next Steps

Bakes (Training)

SDK Quickstart

API Reference

API Playground

​Overview

​Endpoints

​Run Rollout Job

​Get Rollout Status

​Get Rollout Output

​Complete Workflow Example

​Pagination Example

​Understanding Trajectories

​Multiple Trajectories Per Stimulus

​Best Practices

​Error Handling

​Not Found (404)

​Missing Prerequisites (400)

​Next Steps

Bakes (Training)

SDK Quickstart

Overview

Endpoints

Run Rollout Job

Get Rollout Status

Get Rollout Output

Complete Workflow Example

Pagination Example

Understanding Trajectories

Multiple Trajectories Per Stimulus

Best Practices

Error Handling

Not Found (404)

Missing Prerequisites (400)

Next Steps