Create a run

Start a run; dryRun returns the quote without work. Driving evaluations use type closed_loop with datasetId, explicit scenarioIds and policy {kind:model_version,family,modelVersionId} naming an available model of GET /api/v1/evaluation-options (its id and family); each scenario costs that model's pricePerScenarioCents, preparation included. Other evaluation kinds and models remain 403 evaluation_launch_disabled. Paid submissions require maxCostCents and Idempotency-Key. Admission atomically checks balance and reserves the whole quote before work; insufficient credits return 402. Unserved work returns 403 cloud_not_open. Reusing the same key and request returns the original run.

POST /api/v1/runs

Create a run

cURL

curl --request POST \
  --url https://dev.simforge.ai/api/v1/runs \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "type": "render",
  "input": {
    "scenarioId": "<scenario-id>",
    "engine": "3d",
    "preset": "showcase",
    "rig": {
      "schema": "simforge.render-rig/v1",
      "sources": [
        {
          "actorId": "ego",
          "sensorId": "cam-front",
          "outputName": "cam-front",
          "transform": {
            "position": {
              "x": 1.6,
              "y": 1.45,
              "z": 0
            },
            "rotation": {
              "yawRad": 0,
              "pitchRad": -0.0524,
              "rollRad": 0
            }
          },
          "modality": "rgb",
          "attributes": {
            "width": 1280,
            "height": 720,
            "fps": 20,
            "horizontalFovDeg": 90,
            "nearM": 0.05,
            "farM": 1000
          }
        }
      ]
    }
  },
  "maxCostCents": 100
}
'

200

{
  "id": "<string>",
  "type": "<string>",
  "status": "queued",
  "createdAt": "2023-11-07T05:31:56Z",
  "startedAt": "2023-11-07T05:31:56Z",
  "finishedAt": "2023-11-07T05:31:56Z",
  "createdBy": {
    "id": "<string>",
    "email": "<string>"
  },
  "costEstimateCents": 1,
  "costCents": 1,
  "billing": {
    "hold": "pending",
    "heldCents": 1,
    "chargedCents": 1
  },
  "jobs": [
    {
      "id": "<string>",
      "kind": "<string>",
      "status": "queued",
      "attempt": 1,
      "maxAttempts": 123,
      "leaseExpiresAt": "2023-11-07T05:31:56Z",
      "workerClass": "cpu",
      "queue": {
        "blockedBy": [
          "<string>"
        ],
        "ahead": 1,
        "etaSeconds": 1,
        "waitingFor": "worker"
      },
      "errorCode": "<string>",
      "errorReason": "<string>",
      "startedAt": "2023-11-07T05:31:56Z",
      "finishedAt": "2023-11-07T05:31:56Z",
      "progress": "<unknown>"
    }
  ],
  "warnings": [
    {
      "code": "<string>",
      "message": "<string>",
      "subject": "<string>",
      "detail": {},
      "jobId": "<string>"
    }
  ],
  "idempotencyKey": "<string>",
  "input": "<unknown>",
  "published": true,
  "result": "<unknown>",
  "unavailable": {
    "code": "<string>",
    "message": "<string>"
  }
}

Authorizations

Authorization · string · header · required

A sfc_at_… access token from simforge login, or an sfk_… API key. An operation's security lists the scopes the credential must hold.

Body

application/json

type · string · required

Minimum string length: 1

input · object

The run type's input. For type: "render" it is a RenderRunInput; the other run types' inputs are objects of their own.

Option 1

Option 2

Option 3

Show child attributes

dryRun · boolean

maxCostCents · integer

Required for non-dry submissions with a positive cost estimate; the maximum approved price in cents.

Required range: x >= 0

Response

200

application/json

Quote or idempotent replay, including managed driving evaluations.

Option 1

Option 2

Option 3

Option 4

id · string · required

type · string · required

status · enum<string> · required

Available options: queued, running, succeeded, partial, failed, cancelled

createdAt · string<date-time> · required

startedAt · string<date-time> | null · required

finishedAt · string<date-time> | null · required

createdBy · object | null · required

Show child attributes

costEstimateCents · integer | null · required

Required range: x >= 0

costCents · integer | null · required

Required range: x >= 0

billing · object · required

Show child attributes

jobs · object[] · required

Show child attributes

warnings · object[] · required

Show child attributes

idempotencyKey · string | null

Caller-supplied run identity; qualification namespaces are excluded from evaluation suites.

input · any

published · boolean

A run published from another workspace (read-only here): a public benchmark. False for a master render of one of your Sample scenarios. Absent means false (a server older than this field).

result · any

unavailable · object

Present when this run's artifacts and result could not be read: result is null and its artifacts are left out, while every other field still holds. The rest of a page is unaffected.

Show child attributes