---
title: "Start a Monte Carlo job (metered as one run; the first slice runs now)"
method: POST
path: "/v1/jobs/monte-carlo"
tags: ["Jobs"]
---

# Start a Monte Carlo job (metered as one run; the first slice runs now)

`POST /v1/jobs/monte-carlo`

## Request

- Base URL: `https://electronics-architect.com`
- URL: `https://electronics-architect.com/v1/jobs/monte-carlo`
- Auth: HTTP bearer

Scope: `solve`. Validates and caps the design like `POST /v1/designs/monte-carlo` (the trial cap is the plan's; the CPU budget is 5,000,000 node-trials rather than 120,000 — `meta.clamped` says if either applied), charges ONE Monte Carlo run, then runs about 3 s of trials inside this request (allow up to 5 s: the time is checked between trials, and this first slice also validates the design). If that finished the job the response is **200** with `result` — the synchronous summary with `nodeStats` (per-node min / mean / max / stddev) in place of the per-trial array — otherwise **202** with the job's status and progress; poll `GET /v1/jobs/{id}`. Two active jobs per account (429 TOO_MANY_JOBS). `Idempotency-Key` is honoured: a replay returns the same job. Pro and Team only: a Free account is refused with 403 PLAN_REQUIRED (one sentence and the trial link).

## Request body

- object: The design and Monte Carlo options.
  - `design` Design, required (unresolved $ref)
  - `options` object
    - `trials` integer
    - `seed` integer: Seed for the trial generator. Omit for a random seed; the job stores and echoes it.
    - `ambientTemperature` number: Ambient in °C for the thermal estimates. Defaults to the design's own setting, else 25.

## Response `200`

The job finished inside this request.

- JobResponse
  - `job` Job: A Monte Carlo job: status and progress.
    - `id` string: `job_` + 20 characters.
    - `kind` 'monte_carlo'
    - `status` 'queued' | 'running' | 'done' | 'failed' | 'cancelled' | 'expired'
    - `trials` object
      - `total` integer
      - `done` integer
    - `progress` number
    - `sliceInProgress` boolean: Another request is running a slice right now; poll again.
    - `seed` integer
    - `error` string: Only when `failed`.
    - `createdAt` string, date-time
    - `updatedAt` string, date-time
    - `expiresAt` string, date-time
  - `result` JobResult: The synchronous Monte Carlo result without its per-trial array: summary, seed, trialCount, failedTrials, unconvergedTrials, protectionTrips, operatingTrials, plus `nodeStats` — per node, `trials` and min / mean / max / stddev of voltage, current, power and temperature (over every solved trial, as the MCP digest folds them) with `thermalViolations` — and `attribution`.
    - `summary` object
    - `nodeStats` object
    - `seed` integer
    - `trialCount` integer
    - `failedTrials` integer
    - `protectionTrips` integer
    - `operatingTrials` integer
    - `elapsedMs` number: CPU time summed over every slice.
    - `attribution` object
  - `meta` object
    - `schemaVersion` integer
    - `trials` integer
    - `requestedTrials` integer
    - `clamped` boolean
    - `clampedBy` string, nullable
    - `seed` integer
    - `advanced` boolean: On a poll: whether this request ran a slice.
    - `trialsThisSlice` integer: How many trials the slice inside THIS request ran (0 when none ran). Divide the trials left by it for the polls remaining — measured on this job, not estimated from its size.
    - `cancelled` boolean
    - `refunded` boolean
    - `elapsedMs` number
    - `metered` boolean
    - `feature` string
    - `attribution` object

## Other responses

- `202`: The job is running; poll it.
- `400`: VALIDATION_FAILED or INVALID_REQUEST.
- `401`: No key, a browser token instead of a key, an unknown key, or a revoked key (code KEY_REVOKED).
- `402`: QUOTA_EXHAUSTED — the monthly Monte Carlo quota is used up.
- `403`: The key lacks a required scope (INSUFFICIENT_SCOPE), or the call needs a plan the account does not have (PLAN_REQUIRED): on the Free plan, compare, exports, Monte Carlo jobs, AI synthesis, a design with more than one sheet, or a save, share or key past the Free limits; or a team key whose team is no longer paid for.
- `413`: PAYLOAD_TOO_LARGE.
- `429`: RATE_LIMITED (the key's per-minute allowance) or TOO_MANY_JOBS (two jobs are already active for this account).

---

[API](https://skmtc.dev/electronics-architect/apis/electronics-architect-api.md) · [All operations](https://skmtc.dev/electronics-architect/apis/electronics-architect-api/llms.txt) · [OpenAPI document](https://skmtc.dev/electronics-architect/apis/electronics-architect-api/revisions/98066184ba67?raw)