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 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"),  # Default
)
4

Choose a population model

Call the list method on populations to get a list of population models available for simulation.
response = semilattice.populations.list()
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?”.
response = 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

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',
            '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': []
}
7

Poll for results

The simulation will progress through these statuses: Queued → Running → Predicted (or potentially Failed). Predictions typically take less than 20 seconds.Poll for the result using the prediction ID:
import time

prediction = response.data[0]

while prediction.status != "Predicted":
    time.sleep(1)
    response = semilattice.predictions.get(prediction_id=prediction.id)
    prediction = response.data

print("Prediction complete!")
8

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 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.
⌘I