# Optimization

Optimization run endpoints.

## Create an optimization run

> Create a new optimization run for a container using specified base models\
> and evaluation criteria.

```json
{"openapi":"3.1.0","info":{"title":"Maniac Inference Gateway API","version":"1.0.0"},"tags":[{"name":"Optimization","description":"Optimization run endpoints."}],"servers":[{"url":"https://platform.maniac.ai","description":"The Maniac API"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"API key","description":"API key in Authorization header using Bearer <token>."}},"schemas":{"CreateOptimizationRunReq":{"properties":{"container":{"type":"string","minLength":1,"title":"Container","description":"Container id or label."},"base_models":{"items":{"type":"string","minLength":1,"description":"Resource id or label"},"type":"array","title":"Base Models","description":"Base model ids or labels."},"evals":{"items":{"type":"string","minLength":1,"description":"Resource id or label"},"type":"array","title":"Evals","description":"Evaluator ids or labels."},"methods":{"items":{"anyOf":[{"$ref":"#/components/schemas/SFTMethod"},{"$ref":"#/components/schemas/GRPOMethod"}]},"type":"array","title":"Methods","description":"Optimization methods to run."},"data_source":{"anyOf":[{"oneOf":[{"$ref":"#/components/schemas/FileDataSource"},{"$ref":"#/components/schemas/DatasetDataSource"},{"$ref":"#/components/schemas/ContainerDataSource"}],"discriminator":{"propertyName":"type","mapping":{"container":"#/components/schemas/ContainerDataSource","dataset":"#/components/schemas/DatasetDataSource","file":"#/components/schemas/FileDataSource"}}},{"type":"null"}],"title":"Data Source","description":"Optional data source override."},"metadata":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Metadata","description":"Optional metadata."},"environment":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Environment","description":"Execution environment name.","default":"main"}},"type":"object","required":["container","base_models","evals","methods"],"title":"CreateOptimizationRunReq"},"SFTMethod":{"properties":{"type":{"type":"string","const":"sft","title":"Type"},"hyperparameters":{"$ref":"#/components/schemas/SFTHyperparameters"}},"type":"object","required":["type","hyperparameters"],"title":"SFTMethod"},"SFTHyperparameters":{"properties":{"max_steps":{"type":"integer","title":"Max Steps"},"lora_targets":{"items":{"type":"string"},"type":"array","title":"Lora Targets"},"lora_dim":{"anyOf":[{"items":{"type":"integer"},"type":"array"},{"type":"integer"}],"title":"Lora Dim"},"lora_alpha":{"anyOf":[{"items":{"type":"integer"},"type":"array"},{"type":"integer"}],"title":"Lora Alpha"},"per_device_train_batch_size":{"anyOf":[{"items":{"type":"integer"},"type":"array"},{"type":"integer"}],"title":"Per Device Train Batch Size"},"gradient_accumulation_steps":{"anyOf":[{"items":{"type":"integer"},"type":"array"},{"type":"integer"}],"title":"Gradient Accumulation Steps"},"warmup_ratio":{"anyOf":[{"items":{"type":"number"},"type":"array"},{"type":"number"}],"title":"Warmup Ratio"},"optim":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"string"}],"title":"Optim"},"weight_decay":{"anyOf":[{"items":{"type":"number"},"type":"array"},{"type":"number"}],"title":"Weight Decay"},"lr_scheduler_type":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"string"}],"title":"Lr Scheduler Type"},"learning_rate":{"anyOf":[{"items":{"type":"number"},"type":"array"},{"type":"number"}],"title":"Learning Rate"},"seed":{"anyOf":[{"items":{"type":"integer"},"type":"array"},{"type":"integer"}],"title":"Seed"},"mode":{"anyOf":[{"items":{"type":"string","enum":["autoregression","classification","regression"]},"type":"array"},{"type":"string","enum":["autoregression","classification","regression"]}],"title":"Mode"},"num_eval_checkpoints":{"type":"integer","title":"Num Eval Checkpoints","default":7},"train_range":{"type":"string","title":"Train Range","default":"500:20000"},"eval_range":{"type":"string","title":"Eval Range","default":"0:500"},"top_c":{"type":"integer","title":"Top C","default":10},"filter":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Filter"},"max_seq_len":{"type":"integer","title":"Max Seq Len","default":2048},"max_gen_tokens":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Max Gen Tokens"},"target_key":{"type":"string","title":"Target Key","default":"relevance"},"classification_labels":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Classification Labels"}},"additionalProperties":true,"type":"object","required":["max_steps","lora_targets","lora_dim","lora_alpha","per_device_train_batch_size","gradient_accumulation_steps","warmup_ratio","optim","weight_decay","lr_scheduler_type","learning_rate","seed","mode"],"title":"SFTHyperparameters"},"GRPOMethod":{"properties":{"type":{"type":"string","const":"grpo","title":"Type"},"hyperparameters":{"$ref":"#/components/schemas/GRPOHyperparameters"}},"type":"object","required":["type","hyperparameters"],"title":"GRPOMethod"},"GRPOHyperparameters":{"properties":{"lora_alpha":{"items":{"type":"number"},"type":"array","title":"Lora Alpha"},"lora_targets":{"items":{"type":"string"},"type":"array","title":"Lora Targets"},"learning_rate":{"type":"number","title":"Learning Rate"},"batch_size":{"type":"integer","title":"Batch Size"},"max_steps":{"type":"integer","title":"Max Steps"},"seed":{"type":"integer","title":"Seed"},"num_eval_checkpoints":{"type":"integer","title":"Num Eval Checkpoints","default":5}},"type":"object","required":["lora_alpha","lora_targets","learning_rate","batch_size","max_steps","seed"],"title":"GRPOHyperparameters"},"FileDataSource":{"properties":{"range":{"anyOf":[{"type":"string","pattern":"^\\d+:\\d+$","description":"Range to evaluate, as 'start:end' (e.g. '0:200')"},{"type":"null"}],"title":"Range","default":"0:100"},"type":{"type":"string","const":"file","title":"Type"},"file":{"type":"string","minLength":1,"title":"File","description":"Resource id or label"}},"additionalProperties":false,"type":"object","required":["type","file"],"title":"FileDataSource"},"DatasetDataSource":{"properties":{"range":{"anyOf":[{"type":"string","pattern":"^\\d+:\\d+$","description":"Range to evaluate, as 'start:end' (e.g. '0:200')"},{"type":"null"}],"title":"Range","default":"0:100"},"type":{"type":"string","const":"dataset","title":"Type"},"dataset":{"type":"string","minLength":1,"title":"Dataset","description":"Resource id or label"}},"additionalProperties":false,"type":"object","required":["type","dataset"],"title":"DatasetDataSource"},"ContainerDataSource":{"properties":{"range":{"anyOf":[{"type":"string","pattern":"^\\d+:\\d+$","description":"Range to evaluate, as 'start:end' (e.g. '0:200')"},{"type":"null"}],"title":"Range","default":"0:100"},"type":{"type":"string","const":"container","title":"Type"},"container":{"type":"string","minLength":1,"title":"Container","description":"Resource id or label"}},"additionalProperties":false,"type":"object","required":["type","container"],"title":"ContainerDataSource"},"CreateOptimizationRunRes":{"properties":{"created_at":{"type":"string","title":"Created At"},"finished_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Finished At"},"error_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error At"},"status":{"type":"string","title":"Status"},"error":{"anyOf":[{},{"type":"null"}],"title":"Error"},"object":{"type":"string","const":"optimization.run","title":"Object","description":"Object type.","default":"optimization.run"},"id":{"type":"string","title":"Id","description":"Optimization run id."},"container_id":{"type":"string","title":"Container Id","description":"Container id."},"base_models":{"items":{"type":"string"},"type":"array","title":"Base Models","description":"Base model ids."},"methods":{"items":{"anyOf":[{"$ref":"#/components/schemas/SFTMethod"},{"$ref":"#/components/schemas/GRPOMethod"}]},"type":"array","title":"Methods","description":"Optimization methods used."},"dataset":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Dataset","description":"Dataset id."},"evaluators":{"items":{"type":"string"},"type":"array","title":"Evaluators","description":"Evaluator ids."},"metadata":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Metadata","description":"Optional metadata."},"metrics":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Metrics","description":"Optimization metrics."},"spend":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Spend","description":"Estimated spend."},"best_checkpoint":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Best Checkpoint","description":"Best checkpoint id."}},"type":"object","required":["created_at","status","id","container_id","base_models","methods","evaluators"],"title":"CreateOptimizationRunRes"},"ErrorResponse":{"properties":{"error":{"$ref":"#/components/schemas/ManiacError","description":"Error payload."}},"additionalProperties":false,"type":"object","required":["error"],"title":"ErrorResponse","description":"Response body for errors."},"ManiacError":{"properties":{"code":{"type":"string","title":"Code","description":"Machine-readable error code."},"message":{"type":"string","title":"Message","description":"Human-readable error message."},"details":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Details","description":"Additional error details."}},"additionalProperties":false,"type":"object","required":["code","message"],"title":"ManiacError","description":"Standard Maniac API error envelope.\n\nThis matches the shape already used by v2 auth (`detail={\"error\": {...}}`)."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/optimization/runs":{"post":{"tags":["Optimization"],"summary":"Create an optimization run","description":"Create a new optimization run for a container using specified base models\nand evaluation criteria.","operationId":"create_optimization_run_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateOptimizationRunReq"}}},"required":true},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateOptimizationRunRes"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"429":{"description":"Too Many Requests","headers":{"X-RateLimit-Limit":{"description":"Request limit per window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp when the rate limit resets.","schema":{"type":"integer"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"501":{"description":"Not Implemented","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Upstream Unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```