> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mutagent.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Optimization Jobs
> Configure and manage optimization jobs
# Optimization Jobs
An optimization job runs multiple mutation-evaluation cycles to improve a prompt. This guide covers job configuration, lifecycle management, and result handling.
## Creating a Job
```bash CLI theme={null}
# Start an optimization job
mutagent prompts optimize start 123 \
--dataset 456 \
--max-iterations 10 \
--model claude-sonnet-4-6
# With target score and patience
mutagent prompts optimize start 123 \
--dataset 456 \
--max-iterations 15 \
--target-score 0.9 \
--model claude-sonnet-4-6
```
```typescript TypeScript theme={null}
import { Mutagent } from '@mutagent/sdk';
const client = new Mutagent({ apiKey: process.env.MUTAGENT_API_KEY });
const job = await client.optimization.optimizePrompt({
id: 123, // Prompt ID (numeric)
body: {
datasetId: 456,
config: {
maxIterations: 10,
targetScore: 0.9,
patience: 3,
model: 'claude-sonnet-4-6',
},
},
});
console.log('Job ID:', job.id); // UUID
console.log('Status:', job.status); // 'queued'
```
```bash cURL theme={null}
curl -X POST https://api.mutagent.io/api/prompt/123/optimize \
-H "x-api-key: mt_xxxx" \
-H "Content-Type: application/json" \
-d '{
"datasetId": 456,
"config": {
"maxIterations": 10,
"targetScore": 0.9,
"patience": 3,
"model": "claude-sonnet-4-6"
}
}'
```
## Configuration Options
| Option | Type | Default | Description |
| --------------- | ------- | ------- | -------------------------------------------------- |
| `maxIterations` | number | 10 | Maximum optimization cycles (1-100) |
| `targetScore` | number | -- | Stop early when this score is reached (0.0-1.0) |
| `patience` | number | -- | Stop after N iterations without improvement (1-50) |
| `model` | string | -- | LLM model to use for mutation and evaluation |
| `dryRun` | boolean | false | Test mode with mock LLM calls |
| `tuningParams` | object | -- | Additional tuning parameters |
### Configuration Examples
**Conservative optimization:**
```json theme={null}
{
"maxIterations": 20,
"patience": 5,
"model": "claude-sonnet-4-6"
}
```
**Aggressive optimization:**
```json theme={null}
{
"maxIterations": 10,
"targetScore": 0.95,
"model": "claude-sonnet-4-6"
}
```
**Dry run (testing):**
```json theme={null}
{
"maxIterations": 3,
"dryRun": true
}
```
## Job States
Jobs progress through these states:
stateDiagram-v2
\[\*] --> queued
queued --> running
queued --> cancelled
running --> completed
running --> paused
running --> failed
running --> cancelled
paused --> running: Resume
paused --> cancelled
completed --> \[*]
failed --> \[*]
cancelled --> \[\*]
| State | Description | Transitions |
| ----------- | --------------------- | --------------------------------------- |
| `queued` | Waiting to start | -> running, cancelled |
| `running` | Actively optimizing | -> completed, paused, failed, cancelled |
| `paused` | Temporarily stopped | -> running, cancelled |
| `completed` | Successfully finished | Terminal |
| `failed` | Error occurred | Terminal |
| `cancelled` | Manually stopped | Terminal |
## Managing Jobs
### Check Status
```bash CLI theme={null}
# Get job status
mutagent prompts optimize status
```
```typescript TypeScript theme={null}
const status = await client.optimization.getOptimization({ id: jobId });
console.log('Status:', status.status);
console.log('Iteration:', `${status.currentIteration}/${status.maxIterations}`);
console.log('Current Score:', status.currentScore);
console.log('Best Score:', status.bestScore);
console.log('Progress:', `${status.progress}%`);
```
```bash cURL theme={null}
curl https://api.mutagent.io/api/optimization/ \
-H "x-api-key: mt_xxxx"
```
### List Jobs
```typescript theme={null}
const jobs = await client.optimization.listOptimizations({
status: 'running',
limit: 20,
});
jobs.data.forEach(job => {
console.log(`${job.id}: ${job.status} - Score: ${job.currentScore}`);
});
```
### Pause a Job
Temporarily stop a running job (can be resumed later):
```typescript TypeScript theme={null}
await client.optimization.pauseOptimization({ id: jobId });
```
```bash cURL theme={null}
curl -X POST https://api.mutagent.io/api/optimization//pause \
-H "x-api-key: mt_xxxx"
```
Pausing preserves the current best prompt and all progress. The job can be resumed from where it left off.
### Resume a Job
Continue a paused job:
```typescript theme={null}
await client.optimization.resumeOptimization({ id: jobId });
```
### Cancel a Job
Permanently stop a job (cannot be resumed):
```typescript theme={null}
await client.optimization.cancelOptimization({ id: jobId });
```
Cancellation is permanent. If you might want to continue later, use pause instead.
## Getting Results
Retrieve results when a job completes:
```bash CLI theme={null}
# Get optimization results
mutagent prompts optimize results
```
```typescript TypeScript theme={null}
const status = await client.optimization.getOptimization({ id: jobId });
console.log('=== Optimization Results ===');
console.log('Status:', status.status);
console.log('Best Score:', status.bestScore);
console.log('Best Iteration:', status.bestIteration);
console.log('Total Iterations:', status.currentIteration);
console.log('Result Prompt ID:', status.resultPromptId);
// Get score progression
const progress = await client.optimization.getOptimizationProgress({ id: jobId });
console.log('\nScore Progression:');
progress.progression.forEach(p => {
console.log(` Iteration ${p.iteration}: ${p.score}`);
});
```
```bash cURL theme={null}
# Get job status with results
curl https://api.mutagent.io/api/optimization/ \
-H "x-api-key: mt_xxxx"
# Get score progression
curl https://api.mutagent.io/api/optimization//progress \
-H "x-api-key: mt_xxxx"
```
### Job Response Structure
```typescript theme={null}
interface OptimizationJobResponse {
id: string; // UUID
promptId: number; // Source prompt ID
promptGroupId: string; // Prompt group UUID
datasetId: number; // Dataset used for evaluation
status: string; // Job state
config: Record; // Job configuration
progress: number; // Completion percentage
currentIteration: number; // Current iteration
maxIterations: number; // Maximum iterations
currentScore: number | null; // Latest score
bestScore: number | null; // Best score achieved
bestIteration: number | null; // Iteration of best score
resultPromptId: number | null; // ID of optimized prompt (on completion)
error: string | null; // Error message (on failure)
createdAt: string; // Job creation timestamp
startedAt: string | null; // Execution start time
completedAt: string | null; // Completion time
}
```
## Applying Results
When optimization completes, it automatically creates a new prompt version with the optimized content. The `resultPromptId` field points to this new version:
```typescript theme={null}
const status = await client.optimization.getOptimization({ id: jobId });
if (status.status === 'completed' && status.resultPromptId) {
console.log('Optimized prompt created:', status.resultPromptId);
console.log('Best score:', status.bestScore);
// The new prompt version is already linked to the same prompt group
// and marked as the latest version
}
```
## Monitoring Progress
### Polling
Check status periodically via CLI or SDK:
```bash theme={null}
# CLI polling
watch -n 5 mutagent prompts optimize status
```
```typescript theme={null}
async function waitForJob(jobId: string) {
while (true) {
const job = await client.optimization.getOptimization({ id: jobId });
console.log(`Iteration ${job.currentIteration}/${job.maxIterations}`);
console.log(`Current: ${job.currentScore} | Best: ${job.bestScore}`);
if (['completed', 'failed', 'cancelled'].includes(job.status)) {
return job;
}
await new Promise(r => setTimeout(r, 5000));
}
}
```
### Streaming (Recommended)
Use WebSocket streaming for real-time updates. See [Streaming](/platform/optimization/streaming) for full details.
## Best Practices
Optimization is only as good as your test cases. Ensure your dataset is representative and well-designed before optimizing.
A target score of 1.0 is rarely achievable. Set targets based on your baseline and acceptable quality levels.
Set patience (e.g., 3-5) to avoid wasting iterations when the optimizer has converged.
After optimization completes, review the optimized prompt to ensure it maintains the intended behavior and variable structure.
Due to the stochastic nature of optimization, running multiple jobs and comparing results can yield better outcomes.
## Troubleshooting
Check provider configuration and rate limits. Jobs queue when resources are constrained. Verify you have a configured provider in Settings > Providers.
The prompt may be near optimal for the given dataset. Try a different model, adjust the dataset, or review the evaluation criteria.
Free-tier workspaces have a limited number of optimization iteration-runs. The error message shows your usage and limit. Upgrade to increase your limit.
Check the error field in the job status. Common causes: provider API errors, invalid prompt variables, or dataset format issues.