Submit sim job

View as Markdown

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

#Request

POST/v1/simc/jobs

The following can be included in the request body. View in full in API Reference.

#build.channelenumrequired

SimC build channel to run.

nightlyweeklylatest

#build.gitBranchenum

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

midnight

#profile.textstringrequired

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

#runtime.multiStageboolean

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.maxCreditsnumber

Optional spend cap for this job, in credits. When set, the full cap plus any priority fee is reserved at submission, and a job that reaches it is stopped with errorCode max_credits_reached and billed the cap; when omitted, the job reserves credits as it runs. See Credits. The ceiling applied is returned in the response as runtime.ceiling.maxCredits; the maximum is plan.maxCreditsPerJob on GET /v1/simc/usage.

#runtime.maxQueueSecondsnumber

Maximum time this job may wait in the queue before being auto-cancelled, in seconds. Defaults to your plan's queue window when omitted; for the free and paid plans this is 1800 seconds, and custom plans may differ. See plan.defaultQueueSeconds and the plan.maxQueueSeconds maximum on GET /v1/simc/usage. The ceiling applied is returned in the response as runtime.ceiling.queueSeconds.

#priorityenum

Queue priority for this job. Higher priority runs first; same-priority jobs run in submission order. Defaults to standard. high adds a flat per-job priority fee only when it would buy a faster start.

backgroundstandardhigh

#metadataobject

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.bnetClientIdstring

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.bnetClientSecretstring

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.eventsarray

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

job.terminal

#artifacts.htmlboolean

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

#artifacts.csvboolean

Whether to generate a CSV result table (result.csv). Defaults to false. One row per actor (the baseline plus any copy= variants), then one row per profileset; 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.versionenum

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.

#Response

POST/v1/simc/jobs

The following is included in a successful response. View in full in API Reference.

#successboolean

Whether the submission was accepted.

#idstring | null

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

#runtime.ceiling.maxCreditsnumber | null

The per-job credit ceiling that applied to this run: the usage at which the job is stopped with errorCode max_credits_reached. Your runtime.maxCredits when the submission set one; otherwise the plan ceiling. View the maximum at GET /v1/simc/usage under plan.maxCreditsPerJob.

#runtime.ceiling.queueSecondsnumber | 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 plan.maxQueueSeconds.

#runtime.priorityFeeCreditsnumber

Priority fee for this job, included in the credit reservation. 0 when no fee applied.

#links.sharestring

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.manifeststring

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.

#warningsarray

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 for the full shape.

#deprecationsarray

Notices about deprecated request fields your submission used. Omitted when there are none. The job is unaffected; each entry carries field, message, and docsUrl for the replacement.

#Errors

Non-2xx responses share a consistent envelope with a stable code you can branch on. See 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.

JavaScript

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

See 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.

JavaScript

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.

JavaScript

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 for delivery, retries, and signature verification.

#Examples

Submit sim with `nightly` build

Set build.channel to nightly, weekly, or latest. See Simc Builds for how each channel is resolved and compiled.

const secretKey = process.env.SIMMIT_SECRET_KEY

async function submitJob(simcProfile) {
  const response = await fetch('https://api.simmit.com/v1/simc/jobs', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${secretKey}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      build: {
        channel: 'nightly'
      },
      profile: { text: simcProfile }
    })
  })

  if (!response.ok) {
    throw new Error(`Submit failed: ${response.statusText}`)
  }

  const { id, links } = await response.json()
  console.log('Submitted job:', { id, links })
}

await submitJob(
  'warlock=Voidly\nspec=affliction\nload_default_gear=1\nload_default_talents=1'
)

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 for details.

const secretKey = process.env.SIMMIT_SECRET_KEY

async function submitJob(simcProfile) {
  const response = await fetch('https://api.simmit.com/v1/simc/jobs', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${secretKey}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      build: { channel: 'nightly' },
      profile: { text: simcProfile },
      runtime: {
        multiStage: true
      }
    })
  })

  if (!response.ok) {
    throw new Error(`Submit failed: ${response.statusText}`)
  }

  const { id, links } = await response.json()
  console.log('Submitted job:', { id, links })
}

const simcProfileWithProfilesets = '...' // Your simc job with profilesets
await submitJob(simcProfileWithProfilesets)

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.

const secretKey = process.env.SIMMIT_SECRET_KEY
const bnetClientId = process.env.BATTLENET_CLIENT_ID
const bnetClientSecret = process.env.BATTLENET_CLIENT_SECRET

async function submitJob(simcProfile) {
  const response = await fetch('https://api.simmit.com/v1/simc/jobs', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${secretKey}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      build: { channel: 'nightly' },
      profile: { text: simcProfile },
      credentials: {
        bnetClientId,
        bnetClientSecret
      }
    })
  })

  if (!response.ok) {
    throw new Error(`Submit failed: ${response.statusText}`)
  }

  const { id, links } = await response.json()
  console.log('Submitted job:', { id, links })
}

await submitJob('armory=us,area-52,voidly,spec=devourer')

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.

const secretKey = process.env.SIMMIT_SECRET_KEY

async function submitJob(simcProfile) {
  const response = await fetch('https://api.simmit.com/v1/simc/jobs', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${secretKey}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      build: { channel: 'nightly' },
      profile: { text: simcProfile },
      artifacts: { html: true }
    })
  })

  if (!response.ok) {
    throw new Error(`Submit failed: ${response.statusText}`)
  }

  const { id, links } = await response.json()
  console.log('Submitted job:', { id, links })
}

await submitJob(
  'warlock=Voidly\nspec=affliction\nload_default_gear=1\nload_default_talents=1'
)

#Request

#Response

#Errors

#Idempotency

#Metadata

#Webhooks

#Examples

Submit sim with nightly build

Submit sim with multiStage

Submit sim with armory=

Submit sim with HTML report

Submit sim with `nightly` build

Submit sim with `multiStage`

Submit sim with `armory=`