Skip to main content

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 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.

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.
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

FieldTypeDefaultDescription
maxIterationsnumber10Maximum optimization cycles (1-100)
targetScorenumberStop early when this score is reached (0-1)
patiencenumberStop after N iterations with no improvement (1-50)
dryRunbooleanfalseValidate configuration without starting execution
modelstringTarget LLM model for prompt generation
tuningParamsobjectAdvanced 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.
const status = await client.optimization.getOptimization({
  id: 'job-uuid-here',
});

console.log('Status:', status);

Response Fields

FieldTypeDescription
idstringJob UUID
promptIdnumberSource prompt ID
promptGroupIdstringPrompt group UUID
datasetIdnumberDataset used for evaluation
statusstringqueued, running, paused, completed, failed, or cancelled
progressnumberCompletion percentage (0-100)
currentIterationnumberCurrent iteration number
maxIterationsnumberTotal iterations configured
currentScorenumber | nullScore of the current iteration
bestScorenumber | nullBest score achieved so far
bestIterationnumber | nullIteration that achieved best score
resultPromptIdnumber | nullID of the optimized prompt version
errorstring | nullError message if job failed

List Optimization Jobs

Get a paginated list of optimization jobs with optional filters.
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

ParameterTypeDescription
promptGroupIdstringFilter by prompt group UUID
statusstringFilter by status (queued, running, paused, completed, failed, cancelled)
limitnumberResults per page (1-100, default 20)
offsetnumberNumber of results to skip

Get Score Progression

Retrieve the score history across iterations for a job. Useful for charting optimization progress.
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.
await client.optimization.pauseOptimization({
  id: 'job-uuid-here',
});

console.log('Job paused');

Resume Job

Resume a previously paused optimization job.
await client.optimization.resumeOptimization({
  id: 'job-uuid-here',
});

console.log('Job resumed');

Cancel Job

Cancel an optimization job. This action cannot be undone.
await client.optimization.cancelOptimization({
  id: 'job-uuid-here',
});

console.log('Job cancelled');

Poll for Completion

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

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<string, unknown>;
  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

MethodDescription
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 MethodHTTP Endpoint
optimizePromptPOST /api/prompt/:id/optimize
getOptimizationGET /api/optimization/:id
listOptimizationsGET /api/optimization
getOptimizationProgressGET /api/optimization/:id/progress
pauseOptimizationPOST /api/optimization/:id/pause
resumeOptimizationPOST /api/optimization/:id/resume
cancelOptimizationPOST /api/optimization/:id/cancel