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

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?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
    },
    {
      "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
    }
  ],
  "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. Values parse per the axis type declared on the model. Naming one key twice, an unknown key, or an undeclared value 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. Values parse per the axis type declared on the model. Naming one key twice, an unknown key, or an undeclared value 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.

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
}

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": {}
}

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.

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
}