# Submit Sim Job

Send `POST /v1/simc/jobs` with a SimC profile and a build channel. The request and response shapes are below; skip to the [examples](#examples) for working code.

## Request

`POST /v1/simc/jobs`

The following can be included in the request body. View in full in [API Reference](/docs/api-reference#tag/simc/POST/v1/simc/jobs).

**`build.channel`** _(enum, required)_

SimC build channel to run.

`nightly` | `weekly` | `latest`

**`build.gitBranch`** _(enum)_

Optional SimC git branch to override the channel's default.

`midnight`

**`profile.text`** _(string, required)_

SimC profile text to execute (the content you would normally paste into a local simc run). Maximum 2 MB (UTF-8 encoded).

**`runtime.multiStage`** _(boolean)_

Opt-in to multistage execution with automatic culling between stages. When false or omitted, the sim runs in a single pass. Multistage execution is skipped if your input contains unsupported patterns or directives.

**`runtime.maxRuntimeSeconds`** _(number)_

Maximum runtime for this job in seconds. Defaults to 300 seconds when omitted. Jobs that exceed this runtime time out mid-run and are billed for what ran. Determines credit reservation. The ceiling applied is returned in the response as `runtime.ceiling.runtimeSeconds`. View the maximum at `GET /v1/simc/usage` under `limits.maxRuntimeSeconds`.

**`runtime.maxQueueSeconds`** _(number)_

Maximum time this job may wait in the queue before being auto-cancelled, in seconds. Defaults to 1800 seconds when omitted. The ceiling applied is returned in the response as `runtime.ceiling.queueSeconds`.

**`priority`** _(enum)_

Queue priority for this job. Higher priority runs first; same-priority jobs run in submission order. Defaults to `standard`.

`background` | `standard` | `high`

**`metadata`** _(object)_

Opaque metadata echoed back unchanged for your own correlation or labels (for example `profileSource`, `characterRef`). Not used for scheduling or sim execution. Values are strings up to 500 characters.

**`credentials.bnetClientId`** _(string)_

Battle.net API client ID. Must be provided together with `bnetClientSecret`. Lets SimC perform armory/guild imports and resolve item data in your profile that is missing from the current build. Used only for this job and never persisted.

**`credentials.bnetClientSecret`** _(string)_

Battle.net API client secret. Must be provided together with `bnetClientId`. Lets SimC perform armory/guild imports and resolve item data in your profile that is missing from the current build. Used only for this job and never persisted.

**`webhook.events`** _(array)_

Webhook event types to subscribe to for this job. Delivery URL and signing secret come from your webhook configuration.

`job.terminal`

**`artifacts.html`** _(boolean)_

Whether to generate an HTML report. Defaults to `false`. For multistage runs, HTML is generated only for the final stage.

**`artifacts.csv`** _(boolean)_

Whether to generate a CSV result table (`result.csv`). Defaults to `false`. One row per profileset plus the baseline actor; for multistage runs the table covers every profileset across all stages.

Columns: `name,dps_mean,dps_min,dps_max,dps_std_dev,dps_mean_std_dev`

**`artifacts.json.version`** _(enum)_

JSON report schema version. `2` = stable v2.0.0, `3` = v3.0.0-alpha1 (experimental). Defaults to `2`. A JSON report is always generated; use this to select the schema version.

`2` | `3`

## Response

`POST /v1/simc/jobs`

The following is included in a successful response. View in full in [API Reference](/docs/api-reference#tag/simc/POST/v1/simc/jobs).

**`success`** _(boolean)_

Whether the submission was accepted.

**`id`** _(string | null)_

Job ID. Use this to poll status, fetch the final result, and download artifacts.

**`runtime.ceiling.runtimeSeconds`** _(number | null)_

The runtime ceiling that applied to this run, in seconds. View the maximum at `GET /v1/simc/usage` under `limits.maxRuntimeSeconds`.

**`runtime.ceiling.queueSeconds`** _(number | null)_

The queue timeout ceiling that applied to this run, in seconds. Jobs that wait in the queue longer than this are auto-cancelled with `errorCode` `queue_timeout`. View the maximum at `GET /v1/simc/usage` under `limits.maxQueueSeconds`.

**`links.share`** _(string)_

URL to a hosted page for this job. Shows a state-aware page (queued, running, failed) while the job is pre-terminal and the full HTML summary once it completes. The page does not auto-refresh today; reload to see the latest state. Returns `404` after retention expires.

**`links.manifest`** _(string)_

URL to the manifest JSON for the latest attempt. Only present once the job reaches a terminal status. Returns `404` after retention expires. May change between responses if the job is retried.

**`warnings`** _(array)_

Warnings about your input. Omitted when there are none. Covers `iterations=` values above the platform safety cap and `target_error=` values below the platform safety floor. The job still runs at the clamped or floored value. Each entry carries `kind`, `line`, `requested`, `applied`, and `message`; see the [API Reference](/docs/api-reference#tag/simc/POST/v1/simc/jobs) for the full shape.

## Errors

Non-2xx responses share a consistent envelope with a stable `code` you can branch on. See [API Errors](/docs/api/errors) for the shape and the status codes this endpoint can return.

## Idempotency

Submissions accept an idempotency key via the `idempotency-key` header to safely retry without creating duplicate jobs. Reusing the same key with the same payload returns the original job; reusing with a different payload returns `409`.

```js
headers: {
  'idempotency-key': 'req_8f2a9c1e-4b3d-4e5a-9c1f-7d8e2a3b4c5d'
}
```

See [Idempotency](/docs/api-advanced/idempotency) for the full spec.

## Metadata

Attach arbitrary string key/value pairs to a job via `metadata`. Simmit echoes it back unchanged on every job response, useful for correlating jobs with your own request IDs, character references, or profile sources.

```js
body: JSON.stringify({
  build: { channel: 'latest' },
  profile: { text: simcProfile },
  metadata: {
    requestId: 'req_12345',
    characterRef: 'us-area-52-voidly'
  }
})
```

## Webhooks

Subscribe to terminal job events by including `webhook.events` in your submission. Simmit will POST to your configured endpoint when the job reaches a terminal status, like `completed`, `failed`, `cancelled`, or `timed_out`.

```js
body: JSON.stringify({
  build: { channel: 'latest' },
  profile: { text: simcProfile },
  webhook: { events: ['job.terminal'] }
})
```

Endpoint URL and signing secret are configured in the dashboard. See [Webhooks](/docs/api-advanced/webhooks) for delivery, retries, and signature verification.

## Examples

### Submit sim with `nightly` build

Set `build.channel` to `nightly`, `weekly`, or `latest`. See [Simc Builds](/docs/api/simc-builds) for how each channel is resolved and compiled.

**curl**

```bash
# Save your simc profile to profile.simc in the current directory, e.g.:
#   warlock=Voidly
#   spec=affliction
#   load_default_gear=1
#   load_default_talents=1
curl -X POST "https://api.simmit.com/v1/simc/jobs?channel=nightly" \
  -H "Authorization: Bearer $SIMMIT_SECRET_KEY" \
  -H "Content-Type: text/plain" \
  --data-binary @profile.simc
```

### Submit sim with `multiStage`

Set `runtime.multiStage` to `true` to run a job with `profilesets` in up to 3 stages, culling between stages to reduce total runtime. See [Multistage Execution](/docs/api-advanced/multistage-execution) for details.

**curl**

```bash
# Save your simc profile with profilesets to profile.simc in the current directory
curl -X POST "https://api.simmit.com/v1/simc/jobs?channel=nightly&multiStage=true" \
  -H "Authorization: Bearer $SIMMIT_SECRET_KEY" \
  -H "Content-Type: text/plain" \
  --data-binary @profile.simc
```

### Submit sim with `armory=`

Profiles that use the `armory=` directive need a Battle.net client ID and secret so SimC can resolve the lookup. Pass them on `credentials` for JSON, or on `X-Bnet-Client-Id` / `X-Bnet-Client-Secret` headers for plain text. Credentials are used for the job and never persisted.

The same credentials also let SimC resolve item data missing from the current build. If your profile references an item the build does not include, SimC looks it up from Blizzard. Most profiles never need this.

**curl**

```bash
# Set your secrets for SIMMIT_SECRET_KEY, BNET_CLIENT_ID, and BNET_CLIENT_SECRET
# Save your simc profile to profile.simc in the current directory, e.g.:
#   armory=us,area-52,voidly,spec=devourer
curl -X POST "https://api.simmit.com/v1/simc/jobs?channel=nightly" \
  -H "Authorization: Bearer $SIMMIT_SECRET_KEY" \
  -H "Content-Type: text/plain" \
  -H "X-Bnet-Client-Id: $BNET_CLIENT_ID" \
  -H "X-Bnet-Client-Secret: $BNET_CLIENT_SECRET" \
  --data-binary @profile.simc
```

### Submit sim with HTML report

Set `artifacts.html` to `true` to have SimC's HTML report included with the job's artifacts. Default is `false`.

**curl**

```bash
# Save your simc profile to profile.simc in the current directory
curl -X POST "https://api.simmit.com/v1/simc/jobs?channel=nightly&artifactsHtml=true" \
  -H "Authorization: Bearer $SIMMIT_SECRET_KEY" \
  -H "Content-Type: text/plain" \
  --data-binary @profile.simc
```

---

_HTML version: https://docs.staging.simmit.gg/docs/learning/simc-job-submit · Full docs index: https://docs.staging.simmit.gg/llms.txt_