API quickstart

This page walks you through the exact steps to run the bundled alphagen-tutorial.ipynb notebook end-to-end: create an API key, install the Python dependencies, point the notebook at the API, run it, and inspect the results in the webapp.

It reproduces your first calibration in Python — same dataset, same parameters, same model: alphagen-3, the default every plan can run. The notebook stays on the standard calibration path; the walkforward mode is an advanced option and is not used here.

Warning — the model field is enforced against your plan's allowed list. alphagen-2 is restricted to AlphaGen administrators and alphagen-1 is retired, so sending either returns 403. Leave the notebook on alphagen-3.

Info — full REST API reference (every endpoint, every payload schema, "Try it out" sandbox): api.alphagen.improm.ai/docs.

Before you start — team scope

Every AlphaGen resource (project, calibration, prediction) now lives inside a team. Your API token is bound to one specific team; every request made with the token acts on behalf of that team, sees only that team's projects, and counts against that team's plan quotas.

• If you belong to a single team (typical solo signup), the "personal team" auto-created on registration is the default — nothing else to do.
• If you belong to several teams, you will create one API token per team you want to script against.
• Seat requirement — writing operations (calibrate, predict, create/delete/edit) require a builder or manager seat inside the team. viewer and guest seats can list and read only.
• Ejection auto-revokes the token — if an admin removes you from the team the token is bound to, that token immediately returns 401 on every request.

1. Create an API key

1. In the webapp, open Profile → API tokens (/account/api-tokens).
2. Click + New token.
3. Pick a name (e.g. notebook-tutorial), select the team the token should act on behalf of, and set an expiry (30 days is fine for a one-off run).
4. Copy the token shown on screen immediately — it is displayed only once.

The token is a bearer credential. Treat it like a password: never commit it to git, never paste it into a shared notebook cell.

Tip — you can list every team you belong to (and confirm which team a token is bound to) via GET /account/teams. Sample response:

{
  "current_team_id": "e0b31…",
  "teams": [
    { "id": "e0b31…", "name": "My personal team", "seat": "manager", "is_personal": true },
    { "id": "a7c04…", "name": "Acme Trading",     "seat": "builder", "is_personal": false }
  ]
}

2. Install the Python dependencies

The notebook uses Python ≥ 3.10. From a fresh virtual environment:

pip install python-dotenv pandas requests openpyxl jupyter

openpyxl is required by pandas.read_excel; jupyter is what lets you open and run the .ipynb file.

3. Set up your environment variables

Create a .env file in the same folder as the notebook with the following three variables:

# .env
ALPHAGEN_TOKEN="<paste the token you copied at step 1>"
ALPHAGEN_API_URL="https://api.alphagen.improm.ai/api/v1/"
ALPHAGEN_WEBAPP_URL="https://alphagen.improm.ai"

Trailing slash on ALPHAGEN_API_URL is required — the notebook concatenates endpoint paths directly (f"{URL}model/calibrate").

The notebook loads these with python-dotenv in its first cell:

from dotenv import load_dotenv
load_dotenv(dotenv_path=".env")
TOKEN       = os.getenv("ALPHAGEN_TOKEN")
URL         = os.getenv("ALPHAGEN_API_URL")
WEBAPP_URL  = os.getenv("ALPHAGEN_WEBAPP_URL")

4. Download the notebook and the sample data

Download the tutorial notebookalphagen-tutorial.ipynbDownload

German TTF futures prices — ttf.xlsxttf.xlsxDownload

IFS Germany 1-day-ahead weather forecast — forecast_ifs_allemagne_step_24.xlsxforecast_ifs_allemagne_step_24.xlsxDownload

The notebook reads the two spreadsheets from a data/ sub-folder (pd.read_excel("data/ttf.xlsx")), so the layout must be:

your-folder/
├── .env
├── alphagen-tutorial.ipynb
└── data/
    ├── ttf.xlsx
    └── forecast_ifs_allemagne_step_24.xlsx

Dropping the spreadsheets next to the notebook instead of inside data/ is the most common reason the third cell raises FileNotFoundError.

5. Run the notebook

Start Jupyter and open the notebook:

jupyter notebook alphagen-tutorial.ipynb

Run the cells top-to-bottom. Here is what each one does:

Note — a failed job also sets done = true (with failed = true), so the polling loops always terminate and print Calibration failed! rather than spinning.

Tip — every cell is independent once authentication has run. You can re-run the inspection cells without resubmitting the calibration.

Team scope on project names — the project_name parameter is resolved within the token's team. If two teams both contain a project called DEMO_PROJECT, each token only ever sees its own team's copy. To act on a different team's project you must use a token bound to that team.

On the demo dataset both jobs finish quickly — the calibration in well under a minute, the prediction faster still since the model is scored, not refitted. Larger datasets can take several minutes; the polling loops have no timeout.

6. View results in the webapp

The two polling cells print a Dashboard URL the moment the job finishes. Open it in the browser to see the same results visually — the intensity charts, the NAV-vs-benchmark backtest, the per-variable breakdown, and the prediction tables.

• Calibration page: ${ALPHAGEN_WEBAPP_URL}/projects/DEMO_PROJECT/calibrations/<calibration_id>
• Prediction page: ${ALPHAGEN_WEBAPP_URL}/projects/DEMO_PROJECT/calibrations/<calibration_id>/predictions/<prediction_id>

You can also navigate manually: My projects → DEMO_PROJECT → the row tagged tag-of-the-calibration → the linked prediction tag-of-the-prediction.

If a job fails, the polling cell prints Calibration failed! Check at your email for more information — the webapp's calibration row will show a red "failed" status and the same job page will surface the backend error message.

Troubleshooting