Browse historical runs

Sometimes you need more than just the latest run. You might want to review how a model performed over time, check whether a failed run has been retried, or fetch output from a specific past execution. The pd4castr Python SDK gives you full access to a model’s run history with filtering, pagination, and per-run output retrieval.

All examples on this page assume you’ve already created a client:

from pd4castr_api_sdk import Client
 
client = Client(
    client_id="your-client-id",
    client_secret="your-client-secret",
)
 
model_id = "your-model-id"

List recent runs

Use get_model_runs() to retrieve a page of runs for a given model. Each run includes its status, timestamps, and optional sensitivity information.

page = client.get_model_runs(model_id)
 
for run in page.data:
    print(f"{run.run_datetime}  {run.status}")

This returns runs in reverse chronological order (newest first) wrapped in a ModelRunPage containing data, next_cursor, and has_more.

Filter by status

You can narrow results to runs in a specific state by passing the status parameter. For example, to retrieve only completed runs:

page = client.get_model_runs(model_id, status="completed")

You can also pass a list of statuses to match any of them:

page = client.get_model_runs(
    model_id,
    status=["pending", "running"],
)

Valid status values are "pending", "input_files_prepared", "running", "completed", and "failed".

Filter by sensitivity

By default, get_model_runs() returns all runs including both base and sensitivity runs. You can use the sensitivity parameter to narrow results:

# Only base runs (no sensitivities)
base_runs = client.get_model_runs(model_id, sensitivity="base")
 
# Only runs for a specific sensitivity
sensitivity_runs = client.get_model_runs(
    model_id,
    sensitivity="your-sensitivity-id",
)

You can combine sensitivity with status and pagination parameters.

Filter by date range

Use after and before to filter runs by their run_datetime. Both accept ISO 8601 datetime strings and use exclusive comparison (> / <).

# Runs between January and June 2024
page = client.get_model_runs(
    model_id,
    after="2024-01-01T00:00:00Z",
    before="2024-06-01T00:00:00Z",
)

You can combine after/before with status and sensitivity to filter by date, status, and sensitivity.

Paginate through runs

The API uses cursor-based pagination. Pass limit to control the page size. The response includes a next_cursor field you can pass to fetch the next page.

page_size = 10
page = client.get_model_runs(model_id, limit=page_size)
 
while page.data:
    for run in page.data:
        print(f"{run.id}  {run.run_datetime}  {run.status}")
 
    if not page.has_more:
        break
 
    page = client.get_model_runs(
        model_id,
        limit=page_size,
        cursor=page.next_cursor,
    )

You can combine limit, cursor, after, before, and status in a single call to paginate through filtered results.

Fetch a specific run

If you already know a run’s ID, you can fetch it directly with get_model_run():

run = client.get_model_run(model_id, "your-run-id")
 
print(f"Status:    {run.status}")
print(f"Started:   {run.started_at}")
print(f"Completed: {run.completed_at}")
 
if run.sensitivity:
    print(f"Sensitivity: {run.sensitivity.name}")

This is useful when you’ve stored a run ID and want to check its current status or metadata.

Get run output

Once a run has completed, you can retrieve its forecast output with get_model_run_output():

result = client.get_model_run_output(model_id, "your-run-id")
print(result)

This returns a ModelRunOutputResult containing the forecast data for that specific run.

Next steps

• Compare models — learn how to compare output across different models
• Reference — explore every method, data model, and exception in the SDK