> ## Documentation Index > Fetch the complete documentation index at: https://docs.simforge.ai/llms.txt > Use this file to discover all available pages before exploring further. # Get a Factory run and its clips > One Factory run with every clip: its status, what it waits for (`waiting`: render_pending, queued_for_gpu, gpu_worker_starting, gpu_capacity_capped, since when, and `clipsAhead` in the GPU queue), its check (each key actor's detection rate against its own rate on the Helios render, under a versioned threshold set), and short-lived signed links to its generated videos, layouts, labels, quality.json and manifest.json (accepted and flagged clips; a rejected clip is not delivered). ## OpenAPI ````yaml /api-reference/openapi.json get /api/v1/factory/runs/{id} openapi: 3.1.0 info: title: SimForge Cloud API version: '2026-10-24' description: >- The public SimForge API: what `simforge --cloud`, `simforge login` and the Python client call. Authenticate with a bearer token: the access token `simforge login` stores, an AI agent's access token (its recipe is `/auth.md`), or an `sfk_` API key. A `/api/v1` 401 carries `WWW-Authenticate: Bearer resource_metadata="/.well-known/oauth-protected-resource"`. `/api/v1` errors are an `ErrorEnvelope`; `/api/cli` and `/agent` errors are an OAuth error object. Versions: send `SimForge-Version: ` (2026-10-01, 2026-10-21, 2026-10-22, 2026-10-23, 2026-10-24) and every `/api/v1` response is in that version's shape and names it in the same header; this document describes 2026-10-24. A request without the header gets 2026-10-01, where an error's hint is `detail.hint` and `GET /api/v1/evaluations` names its rows `jobs`. A header that is not a date, or a date before 2026-10-01, is `400 bad_request`. Every response also carries `SimForge-Cli-Minimum`: the oldest `simforge` CLI the server serves. Retries: from 2026-10-21, send a new `Idempotency-Key` (1-255 characters) with every POST, PUT, PATCH and DELETE, and the same key when retrying that request. The first request's answer is kept for 24 hours and a repeat gets it again with `Idempotent-Replayed: true`; the key with any other request, or while the first is still running, is `409 idempotency_conflict` (`retryable` while running). A 5xx answer is not kept. Creating an API key refuses a key (its secret is shown once). license: name: Apache-2.0 identifier: Apache-2.0 servers: - url: https://dev.simforge.ai description: Development (dev.simforge.ai) security: [] tags: - name: Sign-in description: >- `simforge login`: OAuth 2.0 device and browser sign-in for the CLI, the session behind a token. AI agents sign in through auth.md (`/auth.md`): register, a person approves, then the claim and JWT-bearer grants. - name: Account description: The principal, its workspaces, API keys and usage, and system status. - name: Runs description: >- Cloud runs (`--cloud`): renders, simulations, Recast log ingestion and transfers, their events and artifacts. - name: Models description: Customer fine-tunes and their workspace-owned model weights. - name: Datasets description: >- Datasets, their files as signed links (`simforge.dataset-files/v1`, `simforge datasets pull`), and copies out of shared datasets (SIMLOG-25k). - name: Maps and vehicles description: >- Maps the workspace can use, the vehicles a scenario can bind and the asset gallery. - name: Authoring description: >- Hosted scenario authoring: drafts, transactions, validation and map discovery. - name: Distribution description: >- The runtime and map pack agreement and signed downloads (`simforge runtime install`, `simforge maps pull`). - name: Telemetry description: Runtime usage telemetry, a condition of the runtime terms. - name: Benchmark description: Renderer benchmark results and scene packs (`simforge bench`). - name: Challenge description: >- The driving challenge: team, registry login and submissions (`simforge challenge`). paths: /api/v1/factory/runs/{id}: get: tags: - Runs summary: Get a Factory run and its clips description: >- One Factory run with every clip: its status, what it waits for (`waiting`: render_pending, queued_for_gpu, gpu_worker_starting, gpu_capacity_capped, since when, and `clipsAhead` in the GPU queue), its check (each key actor's detection rate against its own rate on the Helios render, under a versioned threshold set), and short-lived signed links to its generated videos, layouts, labels, quality.json and manifest.json (accepted and flagged clips; a rejected clip is not delivered). operationId: getFactoryRun parameters: - in: path name: id required: true schema: type: string responses: '200': description: The run and its clips. content: application/json: schema: $ref: '#/components/schemas/FactoryRunDetail' '401': description: The request failed. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '403': description: The request failed. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '404': description: The request failed. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' security: - simforgeToken: - runs:read - artifacts:read components: schemas: FactoryRunDetail: type: object properties: id: type: string status: type: string enum: - queued - running - succeeded - partial - failed - cancelled mode: type: string enum: - positions - simulator lookIds: type: array items: type: string pattern: ^[a-z0-9][a-z0-9-]{0,63}$ seedsPerLook: type: integer exclusiveMinimum: 0 scenarios: type: integer minimum: 0 clips: $ref: '#/components/schemas/FactoryClipCounts' costEstimateCents: type: - integer - 'null' minimum: 0 costCents: type: - integer - 'null' minimum: 0 createdAt: type: string format: date-time finishedAt: type: - string - 'null' format: date-time clipList: type: array items: $ref: '#/components/schemas/FactoryClip' description: Every clip, scenario then look then slot. warnings: type: array items: type: object properties: code: type: string message: type: string scenarioId: type: - string - 'null' lookId: type: - string - 'null' description: >- The look a warning is about (factory_look_unavailable_in_mode: the look replaced); null for a scenario's. required: - code - message - scenarioId - lookId required: - id - status - mode - lookIds - seedsPerLook - scenarios - clips - costEstimateCents - costCents - createdAt - finishedAt - clipList - warnings ErrorEnvelope: type: object properties: error: type: object properties: code: type: string enum: - bad_request - validation_failed - unauthorized - insufficient_scope - workspace_required - not_found - conflict - gone - idempotency_conflict - lease_lost - budget_exceeded - max_cost_required - idempotency_key_required - insufficient_credits - checkout_closed - cloud_not_open - email_unverified - terms_acceptance_required - evaluation_launch_disabled - evaluation_admissions_paused - fine_tunes_not_enabled - model_name_reserved - model_name_invalid - model_name_taken - model_quota_exceeded - checkpoint_too_large - checkpoint_format_unsupported - model_family_not_fine_tunable - checkpoint_file_unexpected - checkpoint_is_offered_model - model_version_exists - param_unknown - param_invalid - param_override_not_allowed - upload_incomplete - upload_mismatch - model_in_use - rate_limited - internal_error reason: type: string hint: type: string param: type: string retryable: type: boolean detail: {} path: type: string requestId: type: string pattern: ^req_[0-9A-HJKMNP-TV-Z]{26}$ required: - code - reason - retryable - requestId required: - error FactoryClipCounts: type: object properties: total: type: integer minimum: 0 inProgress: type: integer minimum: 0 accepted: type: integer minimum: 0 flagged: type: integer minimum: 0 rejected: type: integer minimum: 0 failed: type: integer minimum: 0 required: - total - inProgress - accepted - flagged - rejected - failed FactoryClip: type: object properties: id: type: string description: >- Stable within the run: `//`, n the clip's slot (0-based) among its look's seeds. scenarioId: type: string scenarioName: type: string lookId: type: string pattern: ^[a-z0-9][a-z0-9-]{0,63}$ seed: type: - integer - 'null' minimum: 0 description: The seed of the clip's latest generation; null before it starts. reseeds: type: integer minimum: 0 maximum: 3 description: Free re-seeds used after rejections (at most 3). status: type: string enum: - queued - rendering - generating - checking - accepted - flagged - rejected - failed - cancelled description: >- Where the clip stands: queued, rendering (the Helios render of its scenario), generating (the GPU step), checking (the verdict), then its verdict (accepted, flagged, rejected after its free re-seeds), failed or cancelled. waiting: type: - object - 'null' properties: reason: type: string description: >- One of render_pending, queued_for_gpu, gpu_worker_starting, gpu_capacity_capped; a newer server may add codes. message: type: string since: type: string format: date-time clipsAhead: type: integer minimum: 0 description: >- While the clip waits for a GPU: how many queued GPU attempts the fleet takes before it (oldest first, every workspace's). Absent for render_pending. required: - reason - message - since description: >- What the clip is waiting for while nothing visible happens, and since when: render_pending (its scenario's Helios render is queued), queued_for_gpu (a GPU worker is present or busy; message gives the clip's place in the queue, "Waiting for a GPU, 5 clips ahead"), gpu_worker_starting (no GPU worker was present, so one is starting; a cold start takes minutes; message says which start it is when an earlier one did not come up), gpu_capacity_capped (no worker can start: this environment's GPU-worker or spend cap is reached, as the run's warning says; message gives the clip's place in the queue). since is when the clip began this wait, whatever workers start meanwhile. Null when the clip is not waiting. A clip waiting on a capped, busy fleet is not failed by the 1 h queue deadline; it fails provider_unavailable after 24 h. verdict: type: - string - 'null' enum: - accepted - flagged - rejected - null costCents: type: integer minimum: 0 description: 'What this clip charges: its camera-seconds when accepted, else 0.' check: $ref: '#/components/schemas/FactoryClipCheck' error: type: - object - 'null' properties: code: type: string message: type: string required: - code - message warnings: type: array items: type: object properties: code: type: string message: type: string detail: type: object additionalProperties: {} required: - code - message default: [] description: >- What its scenario's clips do differently while still being made: simulated_past_authored_end (a scenario authored shorter than 20 s, simulated on; detail.authoredEndS, detail.simulatedEndS), scenario_clip_window (a longer one, its first 20 s). files: type: - object - 'null' properties: videos: type: array items: type: object properties: camera: type: string enum: - camera_cross_left_120fov - camera_front_wide_120fov - camera_cross_right_120fov - camera_front_tele_30fov link: $ref: '#/components/schemas/FactorySignedLink' required: - camera - link layouts: type: array items: type: object properties: camera: type: string enum: - camera_cross_left_120fov - camera_front_wide_120fov - camera_cross_right_120fov - camera_front_tele_30fov link: $ref: '#/components/schemas/FactorySignedLink' required: - camera - link labels: type: object properties: boxes2d: $ref: '#/components/schemas/FactorySignedLink' actors3d: $ref: '#/components/schemas/FactorySignedLink' ego: $ref: '#/components/schemas/FactorySignedLink' required: - boxes2d - actors3d - ego quality: $ref: '#/components/schemas/FactorySignedLink' manifest: $ref: '#/components/schemas/FactorySignedLink' required: - videos - layouts - labels - quality - manifest required: - id - scenarioId - scenarioName - lookId - seed - reseeds - status - waiting - verdict - costCents - check - error - files FactoryClipCheck: type: - object - 'null' properties: thresholdsVersion: type: string reasons: type: array items: type: object properties: code: type: string severity: type: string enum: - rejected - flagged - note description: >- What this reason alone makes of the clip; `note`: recorded, it changes nothing. actorId: type: - string - 'null' message: type: string required: - code - severity - actorId - message keyActors: type: array items: type: object properties: actorId: type: string role: type: string enum: - hazard - closest - nearby class: type: - string - 'null' generated: type: object properties: visibleFrames: type: integer hitFrames: type: integer rate: type: - number - 'null' required: - visibleFrames - hitFrames - rate render: type: object properties: visibleFrames: type: integer hitFrames: type: integer rate: type: - number - 'null' required: - visibleFrames - hitFrames - rate relativeRate: type: - number - 'null' description: >- Generated detection rate over the render's for this actor; null when the render cannot measure it. verdict: type: - string - 'null' enum: - accepted - flagged - rejected - null description: >- Null: the actor could not be checked (the render cannot measure it). required: - actorId - role - class - generated - render - relativeRate - verdict lookUnverified: type: array items: type: string description: >- The look's conditions (tags) no check verified, from factory-check/2026-10-28: an accepted clip listing any is billed but not proof they applied. The clip's `manifest.json` carries the same list. Empty when every condition was checked or the look needs none. required: - thresholdsVersion - reasons - keyActors - lookUnverified FactorySignedLink: type: object properties: artifactId: type: string url: type: string minLength: 1 expiresAt: type: string format: date-time sha256: type: string sizeBytes: type: integer minimum: 0 required: - artifactId - url - expiresAt - sha256 - sizeBytes securitySchemes: simforgeToken: type: http scheme: bearer description: >- A `sfc_at_…` access token from `simforge login`, or an `sfk_…` API key. An operation's security lists the scopes the credential must hold. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.