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 Python SDK:

pip install semilattice
3

Initialise the client

import os
from semilattice import Semilattice

semilattice = Semilattice(
    api_key=os.environ.get("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?”.

result = 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',
            'created_at': '2025-06-06T18:18:43.370198Z',
            'simulated_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': []
}
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:

import time

answer_id = result.data[0].id

while result.data[0].status != "Predicted":
    time.sleep(1)
    result = semilattice.answers.get(answer_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',
        'simulated_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 simulated_answer_percentages dictionary 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.