Reference

This is the complete API reference for the pd4castr-api-sdk Python package. It documents every public class, method, data model, and exception.

Client

The Client class is the main entry point for interacting with the pd4castr API.

Constructor

from pd4castr_api_sdk import Client
 
client = Client(
    *,
    client_id: str,
    client_secret: str,
    timeout: float = 30.0,
)

All parameters are keyword-only.

The client supports the context manager protocol, so you can use it with a with statement to automatically close the connection:

with Client(client_id="...", client_secret="...") as client:
    models = client.get_models()

Methods

These are all the public methods available on the Client class.

get_models

client.get_models(
    *,
    time_horizon: str | None = None,
    archived: bool = False,
) -> list[Model]

Returns a list of all models accessible to the authenticated user, including your organisation’s private models and any public models.

Valid time_horizon values:

• "day_ahead"
• "week_ahead"
• "quarterly"
• "historical"

When time_horizon is None, all models are returned regardless of their time horizon.

Returns: list[Model]

get_model

client.get_model(model_id: str) -> Model

Fetches a single model by its unique ID.

Returns: Model

Raises: NotFoundError if no model exists with the given ID.

get_model_sensitivities

client.get_model_sensitivities(
    model_id: str
) -> list[Sensitivity]

Returns the list of sensitivities available for a model.

Returns: list[Sensitivity]

get_current_user

client.get_current_user() -> User

Returns the profile and organisation details for the authenticated user.

Returns: User

get_model_groups

client.get_model_groups() -> list[ModelGroup]

Returns all model groups accessible to the authenticated user. A model group contains one or more model revisions.

Returns: list[ModelGroup]

get_model_group

client.get_model_group(
    model_group_id: str
) -> ModelGroup

Fetches a single model group by its unique ID.

Returns: ModelGroup

Raises: NotFoundError if no model group exists with the given ID.

get_model_group_models

client.get_model_group_models(
    model_group_id: str,
    *,
    archived: bool = False,
) -> list[Model]

Returns all model revisions that belong to a model group.

Returns: list[Model]

get_model_runs

client.get_model_runs(
    model_id: str,
    *,
    limit: int | None = None,
    cursor: str | None = None,
    after: str | None = None,
    before: str | None = None,
    status: str | list[str] | None = None,
    sensitivity: str | None = None,
) -> ModelRunPage

Returns a paginated list of runs for a model, ordered by creation date descending.

When sensitivity is None (the default), all runs are returned including both base and sensitivity runs.

Returns: ModelRunPage

get_model_run

client.get_model_run(
    model_id: str, run_id: str
) -> ModelRun

Fetches a single model run by its unique ID.

Returns: ModelRun

Raises: NotFoundError if no model run exists with the given ID.

get_model_run_output

client.get_model_run_output(
    model_id: str,
    model_run_id: str,
    *,
    comparison_model: str | list[str] | None = None,
) -> ModelRunOutputResult

Fetches the output data for a completed model run. You can optionally include outputs from one or more comparison models for the same run datetime.

Returns: ModelRunOutputResult

get_latest_model

client.get_latest_model(
    model_group_id: str
) -> Model

A convenience method that returns the latest model revision in a model group. It fetches the models in the group and returns the one with the highest revision number.

Returns: Model

Raises: NotFoundError if the model group contains no models.

get_latest_model_run

client.get_latest_model_run(
    model_id: str,
    *,
    sensitivity: str | None = None,
) -> ModelRun

A convenience method that returns the most recent completed run for a model. By default, it returns the latest base run, excluding sensitivity runs.

When sensitivity is None (the default), only base runs are considered.

Returns: ModelRun

Raises: NotFoundError if the model has no matching completed runs.

get_latest_model_run_output

client.get_latest_model_run_output(
    model_id: str,
    *,
    sensitivity: str | None = None,
) -> ModelRunOutputResult

A convenience method that fetches the output data for the most recent completed run of a model. This combines get_latest_model_run and get_model_run_output into a single call. By default, it returns the output from the latest base run.

Returns: ModelRunOutputResult

archive_model

client.archive_model(model_id: str) -> Model

Archives a model, setting archived=True, enabled=False, and public=False. This hides it by default in the pd4castr UI.

Returns: Model — The updated model.

Raises: NotFoundError if the model is not found or not owned by your organisation.

unarchive_model

client.unarchive_model(model_id: str) -> Model

Unarchives a model, setting only archived=False. This makes it visible again in the pd4castr UI, but does not restore enabled or public.

Returns: Model — The updated model.

Raises: NotFoundError if the model is not found or not owned by your organisation.

close

client.close() -> None

Closes the underlying HTTP connection. After calling close(), the client can’t make further requests. If you use the client as a context manager, this is called automatically.

Data Models

All data models use Pydantic and are returned as typed Python objects. Unknown fields from the API are ignored automatically.

Model

Represents a forecast model on the pd4castr platform.

ModelGroup

Represents a group of model revisions. Each time you publish a new revision of a model, it’s added to the same model group.

ModelRun

Represents a single execution of a model.

ModelRunPage

A paginated response containing a list of model runs with cursor information.

ModelRunOutputResult

Contains the output data for a model run, along with any comparison run outputs you requested.

ModelRunWithOutput

A model run together with its forecast output data. This is used inside ModelRunOutputResult.

ModelRunOutputData

A single row of forecast output data. Every row has a forecast_datetime field, plus additional fields that depend on the model’s output specification.

This model uses Pydantic’s extra="allow" configuration, so any fields beyond forecast_datetime are accessible as attributes or via dictionary-style access.

ModelSummary

A compact representation of a model, used inside output results.

Sensitivity

Represents a named sensitivity for a model run.

SensitivitySpecification

Defines a sensitivity configuration on a model.

ModelInputSpecification

Describes an input that a model accepts.

TimeHorizon

Describes the forecast time horizon for a model.

ModelMetadata

Optional metadata associated with a model. All fields default to None.

OutputVariable

Describes a single output variable for the model, including display configuration.

ColumnSpecification

Describes a single column in the model’s output data.

UISpecification

Controls how a column is displayed in the pd4castr UI.

ForecastVariableSpecification

Describes the variable that a model forecasts.

User

Represents an authenticated user on the pd4castr platform.

Organisation

Represents an organisation on the pd4castr platform.

Enums

The SDK defines several string enumerations. Because they extend Python’s StrEnum, you can compare them directly with plain strings.

FileFormat

Supported output file formats for model data.

if model.output_file_format == "parquet":
    print("This model outputs Parquet files")

ModelRunMode

Defines how a model’s runs are triggered.

ModelRunStatus

Represents the lifecycle status of a model run.

Exceptions

The SDK defines two exception types for error handling.

ApiError

Raised when the API returns an HTTP 4xx or 5xx response (except 404, which raises NotFoundError instead).

NotFoundError

Raised when the API returns an HTTP 404 response.

Error Handling Example

This example shows how to handle both exception types.

from pd4castr_api_sdk import Client, ApiError, NotFoundError
 
with Client(client_id="...", client_secret="...") as client:
    try:
        model = client.get_model("non-existent-id")
    except NotFoundError:
        print("Model not found")
    except ApiError as e:
        print(f"API error {e.status_code}: {e.message}")

Next Steps

Now that you’re familiar with the SDK’s API surface, explore these guides to see it in action:

• Discover models — browse and filter available models
• Fetch the latest forecast — retrieve the most recent output for a model
• Browse historical runs — paginate through past model runs
• Compare models — fetch comparison outputs across models