Sim Job Results

View as Markdown

Once a SimC job reaches a terminal status, fetch its full result to get summary metrics, runtime info, and downloadable artifacts. Skip to the examples for code samples.

#Response

GET /v1/simc/jobs/{jobId}/result

Available once the job reaches a terminal status (completed, failed, cancelled, or timed_out). Requests before a terminal status will return 409 with code result_not_ready.

If the job is terminal but produced no result payload (for example, an early failure), the response is 422 with code result_unavailable.

View in full in API Reference.

#Job Fields

Top-level fields describe the job itself, such as its status, runtime, and the build that ran it.

#idstring

Job ID.

#statusenum

Terminal status of the job.

completed | failed | cancelled | timed_out

#priorityenum

Effective priority the job ran at.

background | standard | high

#createdAtstring | null

When the job was submitted.

#startedAtstring | null

When the job began executing. Null when the job never started.

#completedAtstring | null

When the job reached a terminal status.

#cancelRequestedAtstring | null

When a cancel was requested. Null when no cancel has been requested.

#errorCodeenum | null

#statusReasonstring | null

Human-readable explanation paired with errorCode.

#simcExitCodestring | null

SimC process exit code.

#retentionDaysnumber | null

Number of days artifacts are retained after completedAt. After this window, artifact endpoints return 410.

#metadataobject | null

Opaque metadata echoed back exactly as submitted.

#runtime.simDurationMsnumber | null

SimC process wall-clock time in milliseconds. Excludes setup and teardown time. Null if the sim did not start.

#runtime.totalDurationMsnumber | null

Total wall-clock time from job start to completion (milliseconds). Includes sim execution, artifact generation, and post-processing.

#runtime.creditsConsumednumber | null

Credits charged for this job, including any priority fee. 0 for terminal jobs with no billable work.

#runtime.priorityFeeCreditsnumber

Priority surcharge included in creditsConsumed. 0 for jobs submitted at standard or background; otherwise the high-priority fee in effect at submission time.

#runtime.vcpusnumber | null

vCPUs used for this job.

#runtime.ceiling.runtimeSecondsnumber | null

The runtime ceiling that applied to this run, in seconds.

#runtime.ceiling.queueSecondsnumber | null

The queue timeout ceiling that applied to this run, in seconds.

#retriedboolean

True if this job was retried automatically because of a platform error. The response reflects the latest retry attempt.

#build.idstring

Build ID. GET /v1/simc/builds/{id} returns the full build record.

#build.channelenum

SimC build channel this job ran on.

nightly | weekly | latest

#build.commitstring

Git commit hash of the SimC source used for this build.

#build.ciobject | null

Compact upstream CI summary (status and failure count) for this commit. Null when CI data is unavailable.

#links.sharestring

URL to a hosted page for this job. Once the job is terminal, renders the full HTML summary. The page does not auto-refresh today. Returns 404 after retention expires.

#links.manifeststring

URL to the manifest JSON. Returns 404 after retention expires.

#Result

The result block carries the sim's actual output, such as the summary metrics for the main actor, multistage details, and references to downloadable artifacts.

#result.summaryobject | null

Summary metrics for the run. Null when no summary was produced (for example, a failed job).

#result.summary.metricenum

Primary metric used for ranking.

dps

#result.summary.mainActorobject | null

Result for the headline actor (selected by SimC's profileset_main_actor_index directive, default 0). When profileset results are available, this object also carries a profilesets block for the sweep over this actor. For multi-player sims using copy= or set=, per-player results for the remaining actors are in the JSON artifact.

#result.summary.mainActor.namestring

Actor name as defined in the profile.

#result.summary.mainActor.meannumber

Mean DPS across all iterations.

#result.summary.mainActor.mean_errornumber

Standard error of the mean.

#result.summary.mainActor.mean_stddevnumber

Standard deviation of per-iteration DPS.

#result.summary.mainActor.profilesetsobject

Profileset sweep results scoped to this actor. Omitted when no profileset results are available, either because the input declared no profilesets or because none were produced.

#result.summary.mainActor.profilesets.countnumber

Total number of profilesets in the sim result. When this exceeds the length of results, the array was truncated to the top 200 entries by DPS. The full set is available in the JSON artifact.

#result.summary.mainActor.profilesets.resultsarray

Profileset sweep entries, ranked by DPS (highest first). Truncated to the top 200 entries.

#result.summary.multiStageobject

Multistage execution metadata.

#result.summary.multiStage.enabledboolean

Whether multistage execution ran.

#result.summary.multiStage.reasonenum

#result.summary.multiStage.stagesarray

Per-stage funnel for multistage execution, in execution order. Empty for single-pass runs. Each entry includes the stage number, label (initial, intermediate, final), number of profilesets executed, and number culled at the end of the stage.

#result.artifactsarray

Downloadable artifacts produced by this job. Includes the HTML report, JSON report, raw logs, and so on.

#result.artifacts[].idstring

Artifact ID.

#result.artifacts[].urlstring

Stable public URL for downloading this artifact. Valid for the full retention window of the job.

#result.artifacts[].kindstring

Type of artifact (for example html_report, json_report, stdout_log).

#result.artifacts[].mimeTypestring

MIME type of the artifact content.

#result.artifacts[].stagenumber | null

Stage number for multistage execution artifacts (1-indexed). Null for single-run jobs or artifacts not associated with a specific multistage stage.

#Fetching artifacts

Each entry in result.artifacts carries a stable url you can download directly. To resolve a single artifact's URL by ID without refetching the full result, call GET /v1/simc/artifacts/{artifactId}/url; it returns { url }.

#Retention

Artifacts and results stay available for retentionDays after completedAt. After that window:

GET /v1/simc/jobs/{jobId}/result continues to return the job record, but result.artifacts is empty: expired entries are dropped from the array rather than returned with broken URLs.
GET /v1/simc/artifacts/{artifactId}/url returns 410 with code artifact_expired.
links.share and links.manifest return 404.

If you need long-term storage, download the artifacts before retention expires.

#Examples

#Get DPS result

This example function uses the summary to print the player's DPS in the sim.

JavaScript

const secretKey = process.env.SIMMIT_SECRET_KEY

async function printMainActorDps(jobId) {
  // Send GET request to result endpoint
  const response = await fetch(
    `https://api.simmit.com/v1/simc/jobs/${jobId}/result`,
    { headers: { Authorization: `Bearer ${secretKey}` } }
  )

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

  // Extract fields you need, see Response below
  const { result } = await response.json()
  const mainActor = result.summary?.mainActor

  if (!mainActor) {
    console.log('No actor result available')
    return
  }

  console.log('Player DPS:', mainActor.mean)
}

// Use a real job ID
await printMainActorDps('123')

#Get SimC JSON file

This example function finds the JSON report in artifacts, downloads it, and parses it into a variable you can build a report from.

JavaScript

const secretKey = process.env.SIMMIT_SECRET_KEY

async function fetchSimcJson(jobId) {
  // Get the result payload, which lists downloadable artifacts
  const response = await fetch(
    `https://api.simmit.com/v1/simc/jobs/${jobId}/result`,
    { headers: { Authorization: `Bearer ${secretKey}` } }
  )

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

  const { result } = await response.json()

  // Find the JSON report artifact
  const jsonArtifact = result.artifacts.find(a => a.kind === 'json_report')

  if (!jsonArtifact) {
    throw new Error('No JSON report artifact found')
  }

  // The artifact URL is a public, stable download link, no auth header needed
  const reportResponse = await fetch(jsonArtifact.url)

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

  // Parse into a variable you can build a report from
  const report = await reportResponse.json()
  return report
}

// Use a real job ID
const report = await fetchSimcJson('123')

#Get SimC HTML report

This example function finds the HTML report in artifacts and prints its download link. The HTML report exists only if the job was submitted with artifacts.html: true.

JavaScript

const secretKey = process.env.SIMMIT_SECRET_KEY

async function printHtmlReportLink(jobId) {
  // Get the result payload, which lists downloadable artifacts
  const response = await fetch(
    `https://api.simmit.com/v1/simc/jobs/${jobId}/result`,
    { headers: { Authorization: `Bearer ${secretKey}` } }
  )

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

  const { result } = await response.json()

  // Find the HTML report artifact
  const htmlArtifact = result.artifacts.find(a => a.kind === 'html_report')

  if (!htmlArtifact) {
    console.log(
      'No HTML report. Submit with `artifacts.html: true` to generate one'
    )
    return
  }

  console.log('HTML report:', htmlArtifact.url)
}

// Use a real job ID
await printHtmlReportLink('123')

#Get shareable link

This example function pretty-prints links.share (hosted HTML summary) and links.manifest (manifest JSON) for browser-friendly viewing. links.share renders the full summary once the job is terminal; links.manifest is populated then as well.

JavaScript

const secretKey = process.env.SIMMIT_SECRET_KEY

async function printShareLinks(jobId) {
  // Send GET request to the job record endpoint
  const response = await fetch(`https://api.simmit.com/v1/simc/jobs/${jobId}`, {
    headers: { Authorization: `Bearer ${secretKey}` }
  })

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

  const { links } = await response.json()

  console.log('Share page:', links.share)

  if (links.manifest) {
    console.log('Manifest:  ', links.manifest)
  }
}

// Use a real job ID
await printShareLinks('123')

#Get job details

This example function pretty-prints a job's total sim duration, credits consumed, vCPUs used, build commit, and metadata.

JavaScript

const secretKey = process.env.SIMMIT_SECRET_KEY

async function printJobDetails(jobId) {
  // Send GET request to the job record endpoint
  const response = await fetch(`https://api.simmit.com/v1/simc/jobs/${jobId}`, {
    headers: { Authorization: `Bearer ${secretKey}` }
  })

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

  const { status, runtime, build, metadata } = await response.json()

  console.log(`Status:           ${status}`)
  console.log(`Total duration:   ${runtime.totalDurationMs ?? '—'} ms`)
  console.log(`Sim duration:     ${runtime.simDurationMs ?? '—'} ms`)
  console.log(`Credits consumed: ${runtime.creditsConsumed ?? '—'}`)
  console.log(`vCPUs:            ${runtime.vcpus ?? '—'}`)
  console.log(`Build commit:     ${build?.commit ?? '—'}`)
  console.log(`Metadata:         ${JSON.stringify(metadata ?? {}, null, 2)}`)
}

// Use a real job ID
await printJobDetails('123')