Skip to main content

​
Overview

The cluster job system allows you to submit simulations to a distributed computing cluster for faster processing. Jobs are queued, allocated to compute nodes, and executed in parallel.
This is an advanced feature for running extremely large simulation batches (1M+ simulations) across multiple machines.

​
Submit a Job

Submit a new simulation job to the cluster queue. 
POST /api/jobs

​
Request Body

​
financialProfile
object
required
Financial profile for the simulation
​
userInputs
object
required
User inputs (income, age, risk tolerance)
​
goal
object
required
Financial goal details
​
simulationParams
object
Simulation parameters (n_simulations, etc.)

​
Response

​
jobId
string
Unique job identifier for tracking
​
status
string
Initial status (always “queued”)
​
queuePosition
number
Position in the job queue
​
estimatedTimeRemaining
string
Estimated wait time before job starts

​
Example

const response = await fetch('http://localhost:3001/api/jobs', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    financialProfile: { /* ... */ },
    userInputs: { /* ... */ },
    goal: { /* ... */ },
    simulationParams: {
      nSimulations: 5000000  // 5 million simulations
    }
  })
})

const { jobId, queuePosition } = await response.json()
console.log(`Job ${jobId} queued at position ${queuePosition}`)

​
Get Job Status

Check the status and progress of a submitted job. 
GET /api/jobs/:id

​
Response

​
id
string
Job identifier
​
status
string
Current status: queued, running, complete, failed, cancelled
​
progress
number
Completion percentage (0-100)
​
allocatedNodes
number
Number of compute nodes allocated to this job
​
simulationsTotal
number
Total simulations to run
​
simulationsComplete
number
Simulations completed so far
​
queuePosition
number
Position in queue (if still queued)
​
estimatedTimeRemaining
string
Estimated time until completion
​
nodeProgress
array
Per-node progress information
​
results
object
Simulation results (only present when status is “complete”)
​
sensitivityResults
object
Sensitivity analysis results (only present when status is “complete”)
​
error
string
Error message (only present when status is “failed”)

​
Example

const response = await fetch(`http://localhost:3001/api/jobs/${jobId}`)
const job = await response.json()

if (job.status === 'running') {
  console.log(`Progress: ${job.progress}%`)
  console.log(`Nodes: ${job.allocatedNodes}`)
  console.log(`ETA: ${job.estimatedTimeRemaining}`)
} else if (job.status === 'complete') {
  console.log('Job complete!', job.results)
}

​
Cancel a Job

Cancel a queued or running job. 
DELETE /api/jobs/:id

​
Response

​
success
boolean
Whether the job was successfully cancelled
​
message
string
Confirmation message

​
Example

const response = await fetch(`http://localhost:3001/api/jobs/${jobId}`, {
  method: 'DELETE'
})

const { success, message } = await response.json()
You can only cancel jobs that are “queued” or “running”. Completed or failed jobs cannot be cancelled.

​
Get Cluster Status

Retrieve overall cluster health and capacity information. 
GET /api/cluster/status

​
Response

​
totalNodes
number
Total compute nodes in the cluster
​
availableNodes
number
Nodes currently available for new jobs
​
busyNodes
number
Nodes currently running jobs
​
queuedJobs
number
Number of jobs waiting in queue
​
runningJobs
number
Number of jobs currently executing
​
averageWaitTime
string
Average time jobs spend in queue

​
Example

const response = await fetch('http://localhost:3001/api/cluster/status')
const status = await response.json()

console.log(`Cluster: ${status.availableNodes}/${status.totalNodes} nodes available`)
console.log(`Queue: ${status.queuedJobs} jobs waiting`)

​
Polling for Completion

Poll the job status endpoint to monitor progress: 
async function waitForJob(jobId) {
  while (true) {
    const response = await fetch(`http://localhost:3001/api/jobs/${jobId}`)
    const job = await response.json()
    
    if (job.status === 'complete') {
      return job.results
    } else if (job.status === 'failed') {
      throw new Error(job.error)
    }
    
    console.log(`Progress: ${job.progress}%`)
    await new Promise(resolve => setTimeout(resolve, 5000))  // Poll every 5 seconds
  }
}

​
Error Responses

  • 400 Bad Request - Missing required fields
  • 404 Not Found - Job ID not found
  • 500 Internal Server Error - Cluster or job execution error

Build docs developers (and LLMs) love

Get started for freeTalk to us