> ## 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 > Trigger prompt optimization with the TypeScript SDK # Optimization SDK Start and manage automated prompt optimization jobs. The optimization engine iteratively mutates prompt text, evaluates candidates against a dataset, and converges on the highest-scoring variant. B[Optimization Loop] B --> C{Target Score?} C -- Yes --> D[Completed] C -- No --> E{Max Iterations?} E -- No --> B E -- Yes --> D D --> F[Best Prompt Version] `} /> ## Start Optimization Create and start a new optimization job for a prompt. The `id` parameter is the numeric prompt ID, and the body contains the dataset and configuration. ```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: 42, // Prompt ID body: { datasetId: 7, config: { maxIterations: 10, targetScore: 0.9, patience: 3, model: 'claude-sonnet-4-6', tuningParams: { evaluationModel: 'claude-sonnet-4-6', }, }, }, }); console.log('Job started:', job); ``` ### Config Options | Field | Type | Default | Description | | --------------- | --------- | ------- | ----------------------------------------------------------------------------- | | `maxIterations` | `number` | `10` | Maximum optimization cycles (1-100) | | `targetScore` | `number` | -- | Stop early when this score is reached (0-1) | | `patience` | `number` | -- | Stop after N iterations with no improvement (1-50) | | `dryRun` | `boolean` | `false` | Validate configuration without starting execution | | `model` | `string` | -- | Target LLM model for prompt generation | | `tuningParams` | `object` | -- | Advanced tuning parameters (e.g., `{ evaluationModel: 'claude-sonnet-4-6' }`) | ## Get Job Status Get detailed status of an optimization job, including the latest iteration state and recent events. ```typescript theme={null} const status = await client.optimization.getOptimization({ id: 'job-uuid-here', }); console.log('Status:', status); ``` ### Response Fields | Field | Type | Description | | ------------------ | ---------------- | -------------------------------------------------------------------- | | `id` | `string` | Job UUID | | `promptId` | `number` | Source prompt ID | | `promptGroupId` | `string` | Prompt group UUID | | `datasetId` | `number` | Dataset used for evaluation | | `status` | `string` | `queued`, `running`, `paused`, `completed`, `failed`, or `cancelled` | | `progress` | `number` | Completion percentage (0-100) | | `currentIteration` | `number` | Current iteration number | | `maxIterations` | `number` | Total iterations configured | | `currentScore` | `number \| null` | Score of the current iteration | | `bestScore` | `number \| null` | Best score achieved so far | | `bestIteration` | `number \| null` | Iteration that achieved best score | | `resultPromptId` | `number \| null` | ID of the optimized prompt version | | `error` | `string \| null` | Error message if job failed | ## List Optimization Jobs Get a paginated list of optimization jobs with optional filters. ```typescript theme={null} const page = await client.optimization.listOptimizations({ status: 'running', limit: 20, offset: 0, }); for await (const job of page) { console.log(job.id, '-', job.status, `(${job.progress}%)`); } ``` ### Query Parameters | Parameter | Type | Description | | --------------- | -------- | ------------------------------------------------------------------------------------ | | `promptGroupId` | `string` | Filter by prompt group UUID | | `status` | `string` | Filter by status (`queued`, `running`, `paused`, `completed`, `failed`, `cancelled`) | | `limit` | `number` | Results per page (1-100, default 20) | | `offset` | `number` | Number of results to skip | ## Get Score Progression Retrieve the score history across iterations for a job. Useful for charting optimization progress. ```typescript theme={null} const progress = await client.optimization.getOptimizationProgress({ id: 'job-uuid-here', }); console.log('Progression:', progress); ``` The response contains a `progression` array with `{ iteration, score }` entries for each completed iteration. ## Pause Job Pause a running optimization job. The job can be resumed later from where it left off. ```typescript theme={null} await client.optimization.pauseOptimization({ id: 'job-uuid-here', }); console.log('Job paused'); ``` ## Resume Job Resume a previously paused optimization job. ```typescript theme={null} await client.optimization.resumeOptimization({ id: 'job-uuid-here', }); console.log('Job resumed'); ``` ## Cancel Job Cancel an optimization job. This action cannot be undone. ```typescript theme={null} await client.optimization.cancelOptimization({ id: 'job-uuid-here', }); console.log('Job cancelled'); ``` ## Poll for Completion ```typescript theme={null} async function waitForOptimization(jobId: string) { while (true) { const status = await client.optimization.getOptimization({ id: jobId, }); // Access status fields from the response console.log(`Job status: ${JSON.stringify(status)}`); // Check for terminal states const statusStr = JSON.stringify(status); if (statusStr.includes('"completed"')) { console.log('Optimization complete'); return status; } if (statusStr.includes('"failed"') || statusStr.includes('"cancelled"')) { throw new Error('Job ended without completing'); } await new Promise(r => setTimeout(r, 5000)); } } const result = await waitForOptimization('job-uuid-here'); ``` For real-time updates, connect to the WebSocket endpoint at `wss://api.mutagent.io/ws/optimization` and subscribe to a job ID. The server streams events as each iteration completes. ## Type Definitions ```typescript theme={null} interface OptimizeConfig { maxIterations?: number; // Max optimization cycles (default: 10) targetScore?: number; // Stop when score reached (0-1) patience?: number; // Stop after N iterations with no improvement dryRun?: boolean; // Validate config without running model?: string; // Target LLM model tuningParams?: { // Advanced tuning parameters evaluationModel?: string; // Model used for evaluation scoring [key: string]: unknown; }; } interface OptimizeJobResponse { id: string; promptId: number; promptGroupId: string; datasetId: number; status: 'queued' | 'running' | 'paused' | 'completed' | 'failed' | 'cancelled'; config: Record; progress: number; currentIteration: number; maxIterations: number; currentScore: number | null; bestScore: number | null; bestIteration: number | null; resultPromptId: number | null; error: string | null; createdAt: string; startedAt: string | null; completedAt: string | null; } interface ScoreProgression { iteration: number; score: number | null; } ``` ## Method Reference | Method | Description | | ------------------------------------------------ | -------------------------------------------------------- | | `optimization.optimizePrompt({ id, body })` | Start optimization job | | `optimization.getOptimization({ id })` | Get job status | | `optimization.listOptimizations({ ...filters })` | List all jobs with pagination | | `optimization.getOptimizationProgress({ id })` | Get score progression | | `optimization.pauseOptimization({ id })` | Pause job | | `optimization.resumeOptimization({ id })` | Resume job | | `optimization.cancelOptimization({ id })` | Cancel job | | `optimization.getOptimizationStates({ id })` | Retrieve state snapshots for each optimization iteration | ## REST API Reference The SDK methods map to these HTTP endpoints: | SDK Method | HTTP Endpoint | | ------------------------- | ------------------------------------ | | `optimizePrompt` | `POST /api/prompt/:id/optimize` | | `getOptimization` | `GET /api/optimization/:id` | | `listOptimizations` | `GET /api/optimization` | | `getOptimizationProgress` | `GET /api/optimization/:id/progress` | | `pauseOptimization` | `POST /api/optimization/:id/pause` | | `resumeOptimization` | `POST /api/optimization/:id/resume` | | `cancelOptimization` | `POST /api/optimization/:id/cancel` |