SimmitBeta
ResourcesLog in / Sign up

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.

nightly | weekly | latest

#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.maxRuntimeSecondsnumber

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

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.

#priorityenum

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

background | standard | high

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

#credentials.bnetClientSecretstring

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

2 | 3

#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.runtimeSecondsnumber | null

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

#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 limits.maxQueueSeconds.

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

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

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'
)
Pages22