Skip to main content

Optimization SDK

Start and manage automated prompt optimization jobs.

Start Optimization

const job = await client.optimization.postApiPromptByIdOptimize({
  id: 123,  // Prompt ID
  datasetId: 456,
  config: {
    maxIterations: 10,
    targetScore: 0.9,
    mutationStrength: 0.5,
  },
});

console.log('Job ID:', job.jobId);
console.log('Status:', job.status);

Get Job Status

const status = await client.optimization.getApiOptimizationById({
  id: job.jobId,
});

console.log('Status:', status.status);
console.log('Progress:', status.progress, '%');
console.log('Current Score:', status.currentScore);

List Optimization Jobs

const { jobs } = await client.optimization.getApiOptimization({
  limit: 20,
});

jobs?.forEach(j => {
  console.log(j.jobId, '-', j.status, `(${j.progress}%)`);
});

Get Score Progression

const progression = await client.optimization.getApiOptimizationByIdProgress({
  id: job.jobId,
});

progression.scores?.forEach((score, iteration) => {
  console.log(`Iteration ${iteration}: ${score.toFixed(3)}`);
});

Pause Job

await client.optimization.postApiOptimizationByIdPause({
  id: job.jobId,
});

console.log('Job paused');

Resume Job

await client.optimization.postApiOptimizationByIdResume({
  id: job.jobId,
});

console.log('Job resumed');

Cancel Job

await client.optimization.postApiOptimizationByIdCancel({
  id: job.jobId,
});

console.log('Job cancelled');

Poll for Completion

async function waitForOptimization(jobId: string) {
  while (true) {
    const status = await client.optimization.getApiOptimizationById({
      id: jobId,
    });

    console.log(`Progress: ${status.progress}% - Score: ${status.currentScore}`);

    if (status.status === 'completed') {
      return status;
    }

    if (status.status === 'failed' || status.status === 'cancelled') {
      throw new Error(`Job ${status.status}`);
    }

    await new Promise(r => setTimeout(r, 5000));
  }
}

// Usage
const result = await waitForOptimization(job.jobId);
console.log('Final score:', result.finalScore);
console.log('Best prompt version:', result.bestVersionId);

Type Definitions

interface OptimizeJob {
  jobId: string;
  promptId: number;
  datasetId: number;
  status: 'pending' | 'running' | 'paused' | 'completed' | 'failed' | 'cancelled';
  progress: number;
  currentScore?: number;
  finalScore?: number;
  bestVersionId?: number;
  config: OptimizeConfig;
  createdAt: string;
}

interface OptimizeConfig {
  maxIterations?: number;      // Max optimization cycles (default: 10)
  targetScore?: number;        // Stop when score reached (0-1)
  mutationStrength?: number;   // How much to vary prompts (0-1)
  evaluationMetrics?: string[]; // Metrics to optimize for
}

Method Reference

MethodDescription
postApiPromptByIdOptimize({ id, ...config })Start optimization job
getApiOptimization()List all jobs
getApiOptimizationById({ id })Get job status
getApiOptimizationByIdProgress({ id })Get score progression
postApiOptimizationByIdPause({ id })Pause job
postApiOptimizationByIdResume({ id })Resume job
postApiOptimizationByIdCancel({ id })Cancel job