Skip to main content
1

Get your API key

First, sign up for a Semilattice account and create an API key from the dashboard.
2

Install

Install the Semilattice Node.js SDK:
npm install semilattice
3

Initialise the client

const { Semilattice } = require('semilattice');

const semilattice = new Semilattice({
  apiKey: process.env['SEMILATTICE_API_KEY'], // Default
});
4

Choose a population model

Call the list method on populations to get a list of population models available for simulation.
const response = await semilattice.populations.list()
const populations = response.data
Alternatively, you can navigate to the Populations page on your dashboard and select a population model to use. Copy the ID from the population’s metadata or from the address bar.

Click to copy the population model's ID

5

Predict an answer

The predictions.create method simulates how this population would answer a question. Below, we are simulating how this population would respond to the question “Tech debt or unclear error messages, what’s worse?”.
const response = await semilattice.predictions.create({
    population_id: "your-population-id-here",
    predictions: {
        question: "Tech debt or unclear error messages, what's worse?",
        answer_options: ["Tech debt", "Unclear error messages"],
        question_options: { question_type: "single-choice" }
    }
});
6

Poll for results

The API will return immediately, but the simulation runs asynchronously. The initial response will have a status field set to “Queued”:
{
    data: [
        {
            'id': '84a92e29-54e6-4a60-862d-26cd2a78421e',
            'created_at': '2025-06-06T18:18:43.370198Z',
            'predicted_answer_percentages': None,
            'population': 'd670f351-8567-4586-9bba-b81add1bebe3',
            'status': 'Queued',
            'answer_options': ['Tech debt', 'Unclear error messages'],
            'population_name': 'Developers',
            'question': 'Tech debt or unclear error messages, what\'s worse?',
            // ... other fields
        }
    ],
    errors: []
}
The simulation will progress through these statuses: QueuedRunningPredicted (or potentially Failed). Predictions typically take less than 20 seconds.Poll for the result using the prediction ID:
Node.js
let prediction = response.data[0]

while (prediction.status !== "Predicted") {
    await new Promise(resolve => setTimeout(resolve, 1000));
    response = await semilattice.predictions.get(prediction.id);
    prediction = response.data
}

console.log("Prediction complete!");
7

View the results

Once the simulation completes, the predicted_answer_percentages field will contain the prediction results:
{
    data: {
        'id': '84a92e29-54e6-4a60-862d-26cd2a78421e',
        'predicted_answer_percentages': {'Tech debt': 0.5488, 'Unclear error messages': 0.4512},
        'status': 'Predicted',
        'prediction_finished_at': '2025-06-06T18:19:36.418871Z',
        'answer_options': ['Tech debt', 'Unclear error messages'],
        'population_name': 'Developers',
        'question': 'Tech debt or unclear error messages, what\'s worse?',
        // ... other fields
    },
    errors: []
}
The predicted_answer_percentages object shows the predicted percentage of the population that would choose each answer option. In this example, 54.88% would choose “Tech debt” and 45.12% would choose “Unclear error messages”.

Next steps

Now that you’ve run your first simulation, explore the API Reference to learn about all available endpoints and options.
I