Skip to main content

​
Overview

Stimulus (stim) generation creates questions, tasks, or prompts based on the target’s generator configuration and teacher prompt. Stim generates scenarios where the expert behavior would be applied. Stim jobs execute asynchronously and their output is used as input for rollout jobs.

​
Endpoints

​
Run Stim Job

Start a stim job for the target. Endpoint: POST /v1/repo/{repo_name}/targets/{target_name}/stim Request: 
curl -X POST "https://bapi.bread.com.ai/v1/repo/my_repo/targets/coding_target/stim" \
  -H "Authorization: Bearer $BREAD_API_KEY"
​
target_name
string
required
Target name
​
repo_name
string
required
Repository name
Prerequisites:
  • Target must have stim configuration (generators, teacher prompt, student prompt)
Behavior:
  • Idempotent: repeated calls return current state (no duplicate jobs)
  • Asynchronous: returns immediately, job runs in background
SDK Usage: 
# Python: repo_name must be a keyword argument
client.targets.stim.run(target_name="coding_target", repo_name="my_repo")

# With polling (default poll=True)
client.targets.stim.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 output lines generated
  • parameters: object - Job parameters

​
Get Stim Status

Get stim job status. Endpoint: GET /v1/repo/{repo_name}/targets/{target_name}/stim Request: 
curl -X GET "https://bapi.bread.com.ai/v1/repo/my_repo/targets/coding_target/stim" \
  -H "Authorization: Bearer $BREAD_API_KEY"
​
target_name
string
required
Target name
​
repo_name
string
required
Repository name
Response: 200 OK 
{
  "status": "complete",
  "lines": 100,
  "parameters": {}
}
Response Fields:
  • status: string - 'not_started', 'running', 'complete', or 'failed'
  • lines: number - Number of generated stimuli
  • parameters: object - Job configuration

​
Get Stim Output

Get paginated stim output data. Endpoint: GET /v1/repo/{repo_name}/targets/{target_name}/stim/output Request: 
curl -X GET "https://bapi.bread.com.ai/v1/repo/my_repo/targets/coding_target/stim/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": 1000,
  "offset": 0,
  "limit": 100,
  "has_more": true,
  "output": [
    "Write a function to reverse a string",
    "Implement binary search",
    "..."
  ],
  "parameters": {}
}
Response Fields:
  • status: string - Job status
  • lines: number - Total number of output lines
  • offset: number - Starting line offset
  • limit: number - Page size
  • has_more: boolean - Whether more data is available
  • output: Array<string> - List of generated stimuli
  • parameters: object - Stim configuration

​
Complete Workflow Example

1

Start Stim Job

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

Poll Status

# Poll status every 5 seconds
while true; do
  response=$(curl -s -X GET "https://bapi.bread.com.ai/v1/repo/my_repo/targets/coding_target/stim" \
    -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 stimuli"
    break
  elif [ "$status" = "running" ]; then
    echo "Still running... ($lines lines so far)"
  fi
  
  sleep 5
done
3

Fetch Output

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

​
Pagination Example

Fetch all stim output with pagination: 
#!/bin/bash

# Fetch all stim 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/stim/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"
  
  if [ "$has_more" = "false" ]; then
    break
  fi
  
  offset=$((offset + limit))
done

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

​
Job Status States

not_started

Job has not begun execution

running

Job is currently executing

complete

Job finished successfully

​
Best Practices

Wait at least 5-10 seconds between status checks to avoid unnecessary API calls
Use pagination when fetching output to handle large datasets efficiently
Check job status before starting a new run to avoid conflicts
Implement proper error handling for jobs that fail or stall

​
Error Handling

​
Not Found (404)

Target doesn’t exist: 
curl -X POST "https://bapi.bread.com.ai/v1/repo/my_repo/targets/nonexistent/stim" \
  -H "Authorization: Bearer $BREAD_API_KEY"
Response: 404 Not Found 
{
  "error": "Target not found"
}

​
Missing Configuration (400)

Target missing required stim configuration: Response: 400 Bad Request 
{
  "error": "Target must have generators and teacher prompt configured"
}

​
Next Steps

Rollout Generation

Generate trajectories from stim output

SDK Quickstart

Use the SDK for programmatic control