Start model runs

POST/api/v1/predictive-models/runs

Authorization
Permission	`dataPipelines.manage`
Workspace scope	required
Scope target	workspace

Request body

Request body fields
Field	Type	Required	Nullable	Default
objectiveId	string	required	non-null	—
dataDefinitionId	string	required	non-null	—
projectKey	string	required	non-null	—
projectVersion	integer	required	non-null	—
executorKind	string	required	non-null	—
resourceClass	string	required	non-null	—
maxSpendUsdMicros	integer	required	non-null	—
deadlineAt	string	required	non-null	—
executorConfigRef	string	optional	non-null	—
requestKey	string	optional	non-null	—

Response

201

Response fields
Field	Type	Required	Nullable	Default
data	object	required	non-null	—
data.runId	string	required	non-null	—
data.companyId	string	required	non-null	—
data.workspaceId	string	required	non-null	—
data.workUnitId	string	required	non-null	—
data.status	"requested" \| "waiting_capacity" \| "preparing" \| "starting" \| "running" \| "cancel_requested" \| "succeeded" \| "failed" \| "cancelled" \| "blocked"	required	non-null	—
data.revision	integer	required	non-null	—
data.refs	object	required	non-null	—
data.refs.objectiveId	string	required	non-null	—
data.refs.dataDefinitionId	string	required	non-null	—
data.refs.projectKey	string	required	non-null	—
data.refs.projectVersion	integer	required	non-null	—
data.refs.executorKind	string	required	non-null	—
data.refs.resourceClass	string	required	non-null	—
data.refs.maxSpendUsdMicros	integer	required	non-null	—
data.refs.deadlineAt	string	required	non-null	—
data.refs.executorConfigRef	string	optional	non-null	—
data.admissionAttempt	integer	required	non-null	—
data.receipt	object	optional	non-null	—
data.receipt.workUnitId	string	required	non-null	—
data.receipt.revision	string	required	non-null	—
data.receipt.pools	array	required	non-null	—
data.receipt.expiresAtEpochSeconds	integer	required	non-null	—
data.receipt.policy	object	optional	non-null	—
data.receipt.policy.envelopeId	string	required	non-null	—
data.receipt.policy.pinnedAt	string	required	non-null	—
data.receipt.policy.limits	object	required	non-null	—
data.reservationExpiresAt	string	optional	non-null	—
data.blockedReason	string	optional	non-null	—
data.supervisorKey	string	optional	non-null	—
data.createdAt	string	required	non-null	—
data.updatedAt	string	required	non-null	—
data.statusUpdatedAt	string	required	non-null	—

Declared failures

Declared failures
ACCESS_DENIED	403 — not retryable
CORE_ERROR	500 — not retryable
GOVERNANCE_DENIED	403 — not retryable
QUOTA_DENIED	429 — retryable
REQUEST_IDENTITY_INTENT_CONFLICT	409 — not retryable
VALIDATION_ERROR	400 — not retryable
VALIDATION_INPUT_ERROR	400 — not retryable

Durable identity

Durable identity
Kind	request-identity
Request fields	requestKey
Conflict	REQUEST_IDENTITY_INTENT_CONFLICT

Readback

The effect completes asynchronously; reacquire the result with:

predictiveModels.runs.read

Request example

Schematic only. Replace placeholders with real values and include all required nested fields.

POST /api/v1/predictive-models/runs HTTP/1.1
Authorization: Bearer <token>
x-merulan-workspace-id: <workspace-id>
Content-Type: application/json

{
  "objectiveId": "<objectiveId>",
  "dataDefinitionId": "<dataDefinitionId>",
  "projectKey": "<projectKey>",
  "projectVersion": 0,
  "executorKind": "<executorKind>",
  "resourceClass": "<resourceClass>",
  "maxSpendUsdMicros": 0,
  "deadlineAt": "<deadlineAt>"
}