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'], // This is the default and can be omitted
});
4

Choose a population model

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

Simulate an answer

The answers.simulate 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 result = await semilattice.answers.simulate({
    population_id: "your-population-id-here",
    answers: {
        question: "Tech debt or unclear error messages, what's worse?",
        question_options: { question_type: "single-choice" },
        answer_options: ["Tech debt", "Unclear error messages"]
    }
});
6

Handle the response

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',
            benchmark_id: null,
            created_at: '2025-06-06T18:18:43.370198Z',
            simulated_answer_percentages: null,
            ground_answer_counts: null,
            ground_answer_percentages: null,
            kullback_leibler_divergence: null,
            mean_absolute_error: null,
            mean_squared_error: null,
            normalised_kullback_leibler_divergence: null,
            population: 'd670f351-8567-4586-9bba-b81add1bebe3',
            prediction_finished_at: null,
            prediction_started_at: null,
            public: false,
            simulation_engine: 'answers-1',
            status: 'Queued',
            test_finished_at: null,
            test_started_at: null,
            answer_options: ['Tech debt', 'Unclear error messages'],
            population_name: 'Developers',
            question: 'Tech debt or unclear error messages, what\'s worse?',
            question_options: { question_type: 'single-choice' },
            accuracy: null,
            root_mean_squared_error: null
        }
    ],
    errors: []
}
7

Poll for results

The simulation will progress through these statuses: Queued → Running → Predicted (or potentially Failed). Predictions typically take less than a minute.

Poll for the result using the answer ID:

while (result.data[0].status !== "Predicted") {
    await new Promise(resolve => setTimeout(resolve, 1000));
    result = await semilattice.answers.get(result.data[0].id);
}
8

View the results

Once the simulation completes, the simulated_answer_percentages field will contain the prediction results:

{
    data: {
        id: '84a92e29-54e6-4a60-862d-26cd2a78421e',
        benchmark_id: null,
        created_at: '2025-06-06T18:18:43.370198Z',
        simulated_answer_percentages: { 'Tech debt': 0.5488, 'Unclear error messages': 0.4512 },
        ground_answer_counts: null,
        ground_answer_percentages: null,
        kullback_leibler_divergence: null,
        mean_absolute_error: null,
        mean_squared_error: null,
        normalised_kullback_leibler_divergence: null,
        population: 'd670f351-8567-4586-9bba-b81add1bebe3',
        prediction_finished_at: '2025-06-06T18:19:36.418871Z',
        prediction_started_at: '2025-06-06T18:18:45.085523Z',
        public: false,
        simulation_engine: 'answers-1',
        status: 'Predicted',
        test_finished_at: null,
        test_started_at: null,
        answer_options: [ 'Tech debt', 'Unclear error messages' ],
        population_name: 'Developers',
        question: 'Tech debt or unclear error messages, what\'s worse?',
        question_options: { question_type: 'single-choice' },
        accuracy: null,
        root_mean_squared_error: null
    },
    errors: []
}

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