Model Runs

List runs for a model

get/v1/model/:id/run

Returns a paginated list of runs for the model, ordered by creation time descending. By default only completed runs are returned.

Parameters

idstring

required

Unique model identifier.
axisstring[]
Keep only runs whose axis values match key:value, split at the first :. Repeat the parameter with one axis to accept any listed choice, or across axes to require all; an unknown key or a value you may not read is a 400.
sensitivitystring
Filter by sensitivity. Use base for base runs only, or pass a sensitivity id to filter to that variant. Omit to include every sensitivity.
statusstring
Filter by run status. Provide once for a single status, or as a comma-separated list (pending,running,failed). Defaults to completed.
beforestring
Return only runs whose runDatetime is before this ISO 8601 instant.
afterstring
Return only runs whose runDatetime is after this ISO 8601 instant.
cursorstring
Cursor returned as nextCursor from a previous page.
limitnumber
Maximum number of runs to return per page. Defaults to 20.

Returns

dataModelRun[]
Runs in the current page, ordered by creation time descending.
nextCursorstring | null
Cursor for the following page, or null if no further pages exist. Pass it as the cursor query parameter on the next request.
hasMoreboolean
Whether more pages are available after this one.

Error codes

400MODEL_VALIDATION_FAILED
Invalid axis filter: unknown axis key, or a value the model does not declare or you may not read. data.issues names each offending param and the accepted values.
401UNAUTHORIZED
Missing or invalid bearer token.
GET /v1/model/:id/run
curl "https://api.v2.pd4castr.com.au/v1/model/d2f4e0c0-1c1a-4f7c-9b6c-3a4f2c1c1f8d/run?axis=ref_year:2015&sensitivity={sensitivity}&status=completed&before={before}&after={after}&cursor={cursor}&limit={limit}" \
  -H "Authorization: Bearer $PD4CASTR_TOKEN"
Response
{
  "data": [
    {
      "id": "6ee9f6b4-7d31-4d51-8f8c-bd5f9b1f0d5e",
      "status": "completed",
      "modelId": "d2f4e0c0-1c1a-4f7c-9b6c-3a4f2c1c1f8d",
      "createdAt": "2026-04-12T03:14:15.000Z",
      "runDatetime": "2026-04-12T00:00:00.000Z",
      "startedAt": "2026-04-12T03:14:25.000Z",
      "completedAt": "2026-04-12T03:15:08.000Z",
      "erroredAt": null,
      "sensitivity": null,
      "axisValues": null,
      "error": null,
      "containerId": "365abb96b5f9400eb1f4b346480a9b25",
      "hasAggregationErrors": false,
      "outputMetadata": {
        "rowCount": 8760,
        "columns": [
          {
            "name": "forecast_datetime",
            "type": "date"
          },
          {
            "name": "vic1",
            "type": "float"
          },
          {
            "name": "nsw1",
            "type": "float"
          }
        ],
        "datetimeRange": {
          "column": "forecast_datetime",
          "min": "2026-04-12T00:00:00.000Z",
          "max": "2027-04-11T23:00:00.000Z"
        },
        "sizeBytes": 184754,
        "computedAt": "2026-04-12T03:15:20.000Z"
      }
    },
    {
      "id": "5dd8e5a3-6c20-3d40-7e7b-ac4e8a0e9c4d",
      "status": "completed",
      "modelId": "d2f4e0c0-1c1a-4f7c-9b6c-3a4f2c1c1f8d",
      "createdAt": "2026-04-11T03:14:15.000Z",
      "runDatetime": "2026-04-11T00:00:00.000Z",
      "startedAt": "2026-04-11T03:14:23.000Z",
      "completedAt": "2026-04-11T03:15:02.000Z",
      "erroredAt": null,
      "sensitivity": null,
      "axisValues": null,
      "error": null,
      "containerId": "365abb96b5f9400eb1f4b346480a9b25",
      "hasAggregationErrors": false,
      "outputMetadata": {
        "rowCount": 8760,
        "columns": [
          {
            "name": "forecast_datetime",
            "type": "date"
          },
          {
            "name": "vic1",
            "type": "float"
          },
          {
            "name": "nsw1",
            "type": "float"
          }
        ],
        "datetimeRange": {
          "column": "forecast_datetime",
          "min": "2026-04-12T00:00:00.000Z",
          "max": "2027-04-11T23:00:00.000Z"
        },
        "sizeBytes": 184754,
        "computedAt": "2026-04-12T03:15:20.000Z"
      }
    }
  ],
  "nextCursor": "eyJjcmVhdGVkQXQiOiIyMDI2LTA0LTExVDAzOjE0OjE1WiIsImlkIjoiNWRkIn0",
  "hasMore": true
}

Get the latest output

get/v1/model/:id/run/latest/output

Convenience endpoint that returns the completed run's output for the newest run datetime, optionally with comparison runs. By default, restricts to base runs (no sensitivity). axis params select a run variant; without them, the run is the default variant's base run.

Parameters

idstring

required

Unique model identifier.
axisstring[]
Select a run variant as key:value, split at the first :. Repeat the parameter to name several axes; an axis you omit resolves to its default, or to the first value your organisation may read. Values parse per the axis type declared on the model. Naming one key twice, an unknown key, or a value you may not read is a 400.
comparisonModelstring[]
One or more model ids to include as comparison output. Repeat the parameter to pass multiple values.
sensitivitystring
Use base for base runs only, or a sensitivity id to fetch that variant. Defaults to base.

Returns

runModelRunWithOutput
The primary run and its forecast output rows.
comparisonRunsRecord<string, ModelRunWithOutput>
Comparison runs, keyed by model id. Empty when no comparisonModel query parameters were supplied.

Error codes

400MODEL_VALIDATION_FAILED
Invalid variant selection: duplicate axis key, unknown axis key, or a value the model does not declare. data.issues names each offending param and the accepted values.
401UNAUTHORIZED
Missing or invalid bearer token.
404NOT_FOUND
Model not found or has no matching completed runs.
GET /v1/model/:id/run/latest/output
curl "https://api.v2.pd4castr.com.au/v1/model/d2f4e0c0-1c1a-4f7c-9b6c-3a4f2c1c1f8d/run/latest/output?axis=ref_year:2015&comparisonModel={comparisonModel}&sensitivity={sensitivity}" \
  -H "Authorization: Bearer $PD4CASTR_TOKEN"
Response
{
  "run": {
    "id": "6ee9f6b4-7d31-4d51-8f8c-bd5f9b1f0d5e",
    "runDatetime": "2026-04-12T00:00:00.000Z",
    "sensitivity": null,
    "axisValues": null,
    "model": {
      "id": "d2f4e0c0-1c1a-4f7c-9b6c-3a4f2c1c1f8d",
      "displayName": "Demand Forecast (30min)",
      "displayTimezone": "Australia/Sydney",
      "revision": 0
    },
    "colours": {
      "price": "#1f77b4"
    },
    "data": [
      {
        "forecast_datetime": "2026-04-12T00:30:00.000Z",
        "price": 84.12
      },
      {
        "forecast_datetime": "2026-04-12T01:00:00.000Z",
        "price": 81.07
      },
      {
        "forecast_datetime": "2026-04-12T01:30:00.000Z",
        "price": 79.55
      }
    ]
  },
  "comparisonRuns": {}
}

Get the latest run

get/v1/model/:id/run/latest

Convenience endpoint that returns the completed run for the newest run datetime. By default, restricts to base runs (no sensitivity). axis params select a run variant; without them, the run is the default variant's base run.

Parameters

idstring

required

Unique model identifier.
axisstring[]
Select a run variant as key:value, split at the first :. Repeat the parameter to name several axes; an axis you omit resolves to its default, or to the first value your organisation may read. Values parse per the axis type declared on the model. Naming one key twice, an unknown key, or a value you may not read is a 400.
sensitivitystring
Use base for base runs only, or a sensitivity id to fetch that variant. Defaults to base.

Returns

idstring
Unique run identifier.
status"pending" | "input_files_prepared" | "running" | "completed" | "failed"
Current status of the run.
modelIdstring
Unique identifier of the model the run belongs to.
createdAtstring
ISO 8601 timestamp at which the run was created.
runDatetimestring
ISO 8601 reference datetime that the run is forecasting from.
startedAtstring | null
ISO 8601 timestamp at which execution started, or null if the run has not started.
completedAtstring | null
ISO 8601 timestamp at which execution completed, or null if the run is still in progress or failed.
erroredAtstring | null
ISO 8601 timestamp at which the run failed, or null if it did not fail.
sensitivitySensitivity | null
Sensitivity used for the run, or null for a base run.
axisValuesRecord<string, unknown> | null
The run variant's value per declared axis, or null for a run of a model without axes.
errorstring | null
Error message if the run failed, otherwise null.
containerIdstring | null
Opaque identifier of the run's execution environment, when available.
hasAggregationErrorsboolean
Whether any of the run's inputs failed to prepare before execution.
outputMetadataRunDataMetadata | null
Row count, columns, datetime span and size of the run's output, or null when the output has not been measured.

Error codes

400MODEL_VALIDATION_FAILED
Invalid variant selection: duplicate axis key, unknown axis key, or a value the model does not declare. data.issues names each offending param and the accepted values.
401UNAUTHORIZED
Missing or invalid bearer token.
404NOT_FOUND
Model not found or has no matching completed runs.
GET /v1/model/:id/run/latest
curl "https://api.v2.pd4castr.com.au/v1/model/d2f4e0c0-1c1a-4f7c-9b6c-3a4f2c1c1f8d/run/latest?axis=ref_year:2015&sensitivity={sensitivity}" \
  -H "Authorization: Bearer $PD4CASTR_TOKEN"
Response
{
  "id": "6ee9f6b4-7d31-4d51-8f8c-bd5f9b1f0d5e",
  "status": "completed",
  "modelId": "d2f4e0c0-1c1a-4f7c-9b6c-3a4f2c1c1f8d",
  "createdAt": "2026-04-12T03:14:15.000Z",
  "runDatetime": "2026-04-12T00:00:00.000Z",
  "startedAt": "2026-04-12T03:14:25.000Z",
  "completedAt": "2026-04-12T03:15:08.000Z",
  "erroredAt": null,
  "sensitivity": null,
  "axisValues": null,
  "error": null,
  "containerId": "365abb96b5f9400eb1f4b346480a9b25",
  "hasAggregationErrors": false,
  "outputMetadata": {
    "rowCount": 8760,
    "columns": [
      {
        "name": "forecast_datetime",
        "type": "date"
      },
      {
        "name": "vic1",
        "type": "float"
      },
      {
        "name": "nsw1",
        "type": "float"
      }
    ],
    "datetimeRange": {
      "column": "forecast_datetime",
      "min": "2026-04-12T00:00:00.000Z",
      "max": "2027-04-11T23:00:00.000Z"
    },
    "sizeBytes": 184754,
    "computedAt": "2026-04-12T03:15:20.000Z"
  }
}

Get a run's output

get/v1/model/:id/run/:runId/output

Fetches the forecast output for a completed run, optionally with comparison runs.

Parameters

idstring

required

Unique model identifier.
runIdstring

required

Unique run identifier.
comparisonModelstring[]
One or more model ids to include as comparison output. Repeat the parameter to pass multiple values.

Returns

runModelRunWithOutput
The primary run and its forecast output rows.
comparisonRunsRecord<string, ModelRunWithOutput>
Comparison runs, keyed by model id. Empty when no comparisonModel query parameters were supplied.

Error codes

401UNAUTHORIZED
Missing or invalid bearer token.
404NOT_FOUND
No run exists with the given id.
GET /v1/model/:id/run/:runId/output
curl "https://api.v2.pd4castr.com.au/v1/model/d2f4e0c0-1c1a-4f7c-9b6c-3a4f2c1c1f8d/run/6ee9f6b4-7d31-4d51-8f8c-bd5f9b1f0d5e/output?comparisonModel={comparisonModel}" \
  -H "Authorization: Bearer $PD4CASTR_TOKEN"
Response
{
  "run": {
    "id": "6ee9f6b4-7d31-4d51-8f8c-bd5f9b1f0d5e",
    "runDatetime": "2026-04-12T00:00:00.000Z",
    "sensitivity": null,
    "axisValues": null,
    "model": {
      "id": "d2f4e0c0-1c1a-4f7c-9b6c-3a4f2c1c1f8d",
      "displayName": "Demand Forecast (30min)",
      "displayTimezone": "Australia/Sydney",
      "revision": 0
    },
    "colours": {
      "price": "#1f77b4"
    },
    "data": [
      {
        "forecast_datetime": "2026-04-12T00:30:00.000Z",
        "price": 84.12
      },
      {
        "forecast_datetime": "2026-04-12T01:00:00.000Z",
        "price": 81.07
      },
      {
        "forecast_datetime": "2026-04-12T01:30:00.000Z",
        "price": 79.55
      }
    ]
  },
  "comparisonRuns": {}
}

Run a view

post/v1/model/:id/run/:runId/views/:viewId/run

Runs one of the model's published views against a completed run with the given parameter values and returns the result rows with their columns. A parameter left out resolves from the view's default or the run's axis values.

Parameters

idstring

required

Unique model identifier.
runIdstring

required

Unique run identifier.
viewIdstring

required

Unique view identifier.

Request body

Content type: application/json

paramsRecord<string, unknown | null>
The view's parameter values keyed by parameter key. A parameter you leave out resolves from the view's default or the run's axis values.

Returns

columnsModelViewResultColumn[]
Columns in the result, in the view's declared order.
rowsobject[]
Result rows, one object per row keyed by column key.
resolvedParamsRecord<string, unknown | null>
Every declared parameter's resolved value, null where nothing resolved.
fromCacheboolean
Whether the result came from an earlier run with the same parameters.

Error codes

400BAD_REQUEST
A required parameter is missing, or a value is of the wrong type.
401UNAUTHORIZED
Missing or invalid bearer token.
404NOT_FOUND
No model, run, or view exists with the given id, or your organisation may not run this view.
409CONFLICT
The run is not completed. The message names its state.
502BAD_GATEWAY
The view's query failed.
POST /v1/model/:id/run/:runId/views/:viewId/run
curl -X POST "https://api.v2.pd4castr.com.au/v1/model/d2f4e0c0-1c1a-4f7c-9b6c-3a4f2c1c1f8d/run/6ee9f6b4-7d31-4d51-8f8c-bd5f9b1f0d5e/views/9c1d6c9f-0a8e-4f7c-9b6c-3a4f2c1c1f8d/run" \
  -H "Authorization: Bearer $PD4CASTR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"params":{"region":"NSW1"}}'
Response
{
  "columns": [
    {
      "key": "region",
      "type": "string",
      "role": "dimension",
      "label": "Region",
      "unit": null,
      "format": null
    },
    {
      "key": "price",
      "type": "number",
      "role": "measure",
      "label": "Price",
      "unit": "AUD/MWh",
      "format": "currency"
    }
  ],
  "rows": [
    {
      "region": "NSW1",
      "price": 84.12
    },
    {
      "region": "VIC1",
      "price": 81.07
    }
  ],
  "resolvedParams": {
    "region": "NSW1"
  },
  "fromCache": false
}

Get a run's input file

get/v1/model/:id/run/:runId/input/:inputKey

Returns the input file the run consumed under inputKey, exactly as the model read it and in the format format on the model input. Set link=true to receive a signed, time-limited download link instead of the file. Available only for input keys your organisation has been granted.

Parameters

idstring

required

Unique model identifier.
runIdstring

required

Unique run identifier.
inputKeystring

required

The input key declared by the model.
linkboolean
Answer with a signed download link to the file instead of the file itself. The link needs no authentication header and stops working at its expiresAt. Defaults to false.

Returns

The input file, or the download link when link=true. The Content-Type follows the input format: application/json, text/csv or application/vnd.apache.parquet for the file, application/json for the link.

idstring
Unique input identifier.
keystring
The input key declared by the model.
format"json" | "csv" | "parquet"
The format the model consumed the file in.
urlstring
A signed link that downloads the file exactly as the model read it. No authentication header is needed; the link stops working at expiresAt.
expiresAtstring
ISO 8601 datetime after which the link no longer works.
metadataRunDataMetadata | null
Row count, columns, datetime span and size of the file, or null when the file has not been measured.

Error codes

400VALIDATION_FAILED
link is not a boolean. data.issues names the offending param.
401UNAUTHORIZED
Missing or invalid bearer token.
404NOT_FOUND
No run exists with the given id, or the run has no input under inputKey that your organisation may read.
GET /v1/model/:id/run/:runId/input/:inputKey
curl "https://api.v2.pd4castr.com.au/v1/model/d2f4e0c0-1c1a-4f7c-9b6c-3a4f2c1c1f8d/run/6ee9f6b4-7d31-4d51-8f8c-bd5f9b1f0d5e/input/demand_forecast?link=false" \
  -H "Authorization: Bearer $PD4CASTR_TOKEN"
Response
{
  "id": "b2f4e0c0-1c1a-4f7c-9b6c-3a4f2c1c1f8d",
  "key": "demand_forecast",
  "format": "json",
  "url": "https://pd4castr-model-run-inputs.s3.ap-southeast-2.amazonaws.com/runs/6ee9f6b4-7d31-4d51-8f8c-bd5f9b1f0d5e/b2f4e0c0-1c1a-4f7c-9b6c-3a4f2c1c1f8d.json?X-Amz-Expires=1800&X-Amz-Signature=…",
  "expiresAt": "2026-04-12T00:30:00.000Z",
  "metadata": {
    "rowCount": 17520,
    "columns": [
      {
        "name": "settlement_date",
        "type": "TIMESTAMP"
      },
      {
        "name": "demand_mw",
        "type": "DOUBLE"
      }
    ],
    "datetimeRange": {
      "column": "settlement_date",
      "min": "2026-04-12T00:00:00.000Z",
      "max": "2026-04-12T23:30:00.000Z"
    },
    "sizeBytes": 4096,
    "computedAt": "2026-04-12T00:05:00.000Z"
  }
}

Get a run

get/v1/model/:id/run/:runId

Returns a single run by its unique id.

Parameters

idstring

required

Unique model identifier.
runIdstring

required

Unique run identifier.

Returns

idstring
Unique run identifier.
status"pending" | "input_files_prepared" | "running" | "completed" | "failed"
Current status of the run.
modelIdstring
Unique identifier of the model the run belongs to.
createdAtstring
ISO 8601 timestamp at which the run was created.
runDatetimestring
ISO 8601 reference datetime that the run is forecasting from.
startedAtstring | null
ISO 8601 timestamp at which execution started, or null if the run has not started.
completedAtstring | null
ISO 8601 timestamp at which execution completed, or null if the run is still in progress or failed.
erroredAtstring | null
ISO 8601 timestamp at which the run failed, or null if it did not fail.
sensitivitySensitivity | null
Sensitivity used for the run, or null for a base run.
axisValuesRecord<string, unknown> | null
The run variant's value per declared axis, or null for a run of a model without axes.
errorstring | null
Error message if the run failed, otherwise null.
containerIdstring | null
Opaque identifier of the run's execution environment, when available.
hasAggregationErrorsboolean
Whether any of the run's inputs failed to prepare before execution.
outputMetadataRunDataMetadata | null
Row count, columns, datetime span and size of the run's output, or null when the output has not been measured.

Error codes

401UNAUTHORIZED
Missing or invalid bearer token.
404NOT_FOUND
No run exists with the given id.
GET /v1/model/:id/run/:runId
curl "https://api.v2.pd4castr.com.au/v1/model/d2f4e0c0-1c1a-4f7c-9b6c-3a4f2c1c1f8d/run/6ee9f6b4-7d31-4d51-8f8c-bd5f9b1f0d5e" \
  -H "Authorization: Bearer $PD4CASTR_TOKEN"
Response
{
  "id": "6ee9f6b4-7d31-4d51-8f8c-bd5f9b1f0d5e",
  "status": "completed",
  "modelId": "d2f4e0c0-1c1a-4f7c-9b6c-3a4f2c1c1f8d",
  "createdAt": "2026-04-12T03:14:15.000Z",
  "runDatetime": "2026-04-12T00:00:00.000Z",
  "startedAt": "2026-04-12T03:14:25.000Z",
  "completedAt": "2026-04-12T03:15:08.000Z",
  "erroredAt": null,
  "sensitivity": null,
  "axisValues": null,
  "error": null,
  "containerId": "365abb96b5f9400eb1f4b346480a9b25",
  "hasAggregationErrors": false,
  "outputMetadata": {
    "rowCount": 8760,
    "columns": [
      {
        "name": "forecast_datetime",
        "type": "date"
      },
      {
        "name": "vic1",
        "type": "float"
      },
      {
        "name": "nsw1",
        "type": "float"
      }
    ],
    "datetimeRange": {
      "column": "forecast_datetime",
      "min": "2026-04-12T00:00:00.000Z",
      "max": "2027-04-11T23:00:00.000Z"
    },
    "sizeBytes": 184754,
    "computedAt": "2026-04-12T03:15:20.000Z"
  }
}