Skip to main content

​
Create optimization

curl -X POST http://127.0.0.1:8000/optimizations \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "MA Crossover Optimization",
    "description": "Find optimal periods for moving average crossover",
    "search_space": {
      "parameters": [
        {
          "name": "short_period",
          "kind": "int_range",
          "low": 5,
          "high": 50
        },
        {
          "name": "long_period",
          "kind": "int_range",
          "low": 20,
          "high": 200
        }
      ]
    },
    "strategy": "random",
    "max_trials": 100,
    "concurrency": 4,
    "objective_metric": "sharpe_ratio",
    "direction": "maximize",
    "base_backtest": {
      "symbols": ["AAPL"],
      "start_date": "2023-01-01T00:00:00Z",
      "end_date": "2023-12-31T23:59:59Z",
      "resolution": "day",
      "strategy": {
        "name": "moving_average_crossover",
        "params": {}
      },
      "initial_capital": 1000000.0
    }
  }'
Create and start a new parameter optimization run. The optimization executes asynchronously and returns immediately with an optimization_id and initial status.

​
Request body

​
name
string
required
Descriptive name for the optimization run (1-256 chars)Example: "MA Crossover Optimization"
​
description
string
Optional description (max 1024 chars)Example: "Find optimal periods for moving average crossover"
​
search_space
object
required
Parameter search space configuration
​
search_space.parameters
array
required
List of parameters to optimize (1-50 parameters)
​
strategy
string
default:"random"
Search strategyOptions: grid, random, bayesian
​
max_trials
integer
default:"100"
Maximum number of trials to run (1-10,000)
​
concurrency
integer
default:"4"
Maximum concurrent trials (1-128)
​
objective_metric
string
default:"sharpe_ratio"
Metric to optimize (max 64 chars)Common options: sharpe_ratio, sortino_ratio, calmar_ratio, total_return, max_drawdown
​
direction
string
default:"maximize"
Optimization directionOptions: maximize, minimize
​
base_backtest
object
required
Base backtest configuration that trials will override with sampled parametersSame structure as POST /backtests request body
​
exploration_weight
number
default:"0.3"
Exploration vs exploitation weight for Bayesian optimization (0.0-1.0)
​
grid_steps
integer
default:"5"
Steps per parameter for grid search (2-100)
​
ray_cluster
object
Optional Ray cluster configuration for distributed execution
​
ray_cluster.address
string
default:"ray://localhost:10001"
Ray cluster address
​
ray_cluster.namespace
string
default:"glowback"
Ray namespace
​
ray_cluster.max_concurrent_tasks
integer
default:"4"
Maximum concurrent Ray tasks (1-256)
​
ray_cluster.num_cpus
number
default:"1.0"
CPUs per task
​
ray_cluster.num_gpus
number
default:"0.0"
GPUs per task

​
Response

​
optimization_id
string
Unique identifier for the optimization run
​
name
string
Optimization name
​
state
string
Current state: pending, running, completed, failed, cancelled
​
strategy
string
Search strategy being used
​
objective_metric
string
Metric being optimized
​
direction
string
Optimization direction
​
max_trials
integer
Maximum trials configured
​
trials_completed
integer
Number of completed trials
​
trials_failed
integer
Number of failed trials
​
trials_running
integer
Number of currently running trials
​
best_trial
object
Best trial found so far (null if none completed)
​
created_at
datetime
Creation timestamp
​
started_at
datetime
Start timestamp
​
finished_at
datetime
Completion timestamp

​
List optimizations

curl http://127.0.0.1:8000/optimizations?limit=50 \
  -H "X-API-Key: your-api-key"
List all optimization runs, most recent first.

​
Query parameters

​
limit
integer
default:"50"
Maximum number of results (1-200)

​
Response

Returns an array of OptimizationStatus objects.

​
Get optimization status

curl http://127.0.0.1:8000/optimizations/{opt_id} \
  -H "X-API-Key: your-api-key"
Get the current status of an optimization run.

​
Path parameters

​
opt_id
string
required
Optimization ID

​
Response

Returns an OptimizationStatus object with current progress.

​
Get optimization results

curl http://127.0.0.1:8000/optimizations/{opt_id}/results \
  -H "X-API-Key: your-api-key"
Retrieve detailed results including all trials.

​
Path parameters

​
opt_id
string
required
Optimization ID

​
Response

​
optimization_id
string
Optimization ID
​
state
string
Final state
​
best_trial
object
Best trial details
​
all_trials
array
Complete list of all trials
​
total_duration_seconds
integer
Total optimization duration
​
search_space
object
Search space configuration used

​
Cancel optimization

curl -X POST http://127.0.0.1:8000/optimizations/{opt_id}/cancel \
  -H "X-API-Key: your-api-key"
Cancel a running optimization.

​
Path parameters

​
opt_id
string
required
Optimization ID

​
Response

Returns 204 No Content on success.

​
Next steps

Authentication

API key setup and security

Backtest endpoints

Run individual backtests

Build docs developers (and LLMs) love

Get started for freeTalk to us