# 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`. Used only for this job to allow SimC armory/guild imports; never persisted with your job data.

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

Battle.net API client secret. Must be provided together with `bnetClientId`. Used only for this job to allow SimC armory/guild imports; never persisted with your job data.

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

**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://simmit.com/docs/learning/simc-job-submit · Full docs index: https://simmit.com/llms.txt_