> ## 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. # Report runtime usage > Deliver one sealed usage batch from an installed runtime (CLI credential; a condition of the SimForge account and download terms). A v2 batch is refused unless its agreementVersion is the account's latest accepted agreement and lists the v2 records ## OpenAPI ````yaml /api-reference/openapi.json post /api/v1/telemetry openapi: 3.1.0 info: title: SimForge Cloud API version: '2026-10-29' 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, 2026-10-28, 2026-10-29) and every `/api/v1` response is in that version's shape and names it in the same header; this document describes 2026-10-29. 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/telemetry: post: tags: - Telemetry summary: Report runtime usage description: >- Deliver one sealed usage batch from an installed runtime (CLI credential; a condition of the SimForge account and download terms). A v2 batch is refused unless its agreementVersion is the account's latest accepted agreement and lists the v2 records operationId: reportRuntimeUsage requestBody: required: true content: application/json: schema: oneOf: - $ref: '#/components/schemas/TelemetryBatch' - $ref: '#/components/schemas/TelemetryBatchV2' responses: '200': description: Stored, or already stored under this batch ID. content: application/json: schema: $ref: '#/components/schemas/TelemetryReceipt' '400': description: The request failed. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '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' '429': description: The request failed. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' security: - simforgeToken: [] components: schemas: TelemetryBatch: type: object properties: schema: type: string enum: - simforge.usage-batch/v1 batchId: type: string pattern: >- ^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$ sealedAt: type: string pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$ accountId: type: string minLength: 1 maxLength: 128 installId: type: string pattern: >- ^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$ machine: type: object properties: os: type: string pattern: ^[a-z][a-z0-9-]{0,31}$ arch: type: string pattern: ^[a-z0-9_]{1,16}$ gpus: type: array items: type: object properties: model: type: string minLength: 1 maxLength: 128 pattern: ^[\x20-\x7e]+$ vramMib: type: - integer - 'null' minimum: 0 maximum: 1000000000000 driver: type: - string - 'null' maxLength: 64 pattern: ^[\x20-\x7e]*$ required: - model - vramMib - driver additionalProperties: false maxItems: 16 gpuCount: type: integer minimum: 0 maximum: 16 gpuProbe: type: string enum: - nvidia-smi - none required: - os - arch - gpus - gpuCount - gpuProbe additionalProperties: false droppedEvents: type: integer minimum: 0 maximum: 1000000000000 events: type: array items: type: object properties: eventId: type: string pattern: >- ^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$ finishedAt: type: string pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$ runtimeVersion: type: string pattern: ^[0-9A-Za-z.+-]{1,32}$ cliVersion: type: - string - 'null' pattern: ^[0-9A-Za-z.+-]{1,32}$ kind: type: string enum: - simulate - compile - render - preview - env - evaluate - transfer - export - command command: type: string pattern: ^[a-z][a-z0-9-]{0,31}$ renderMode: type: - string - 'null' enum: - 2d - schematic - 3d - null renderProfile: type: - string - 'null' enum: - training - showcase - schematic - null sensors: type: - integer - 'null' minimum: 0 maximum: 1000000000000 frames: type: - integer - 'null' minimum: 0 maximum: 1000000000000 wallSeconds: type: number minimum: 0 maximum: 100000000 gpuBusySeconds: type: - number - 'null' minimum: 0 maximum: 100000000 outcome: type: string enum: - ok - findings - error errorCode: type: - string - 'null' pattern: ^[a-z][a-z0-9_]{0,63}$ episodes: type: integer minimum: 0 maximum: 1000000000000 envSteps: type: integer minimum: 0 maximum: 1000000000000 map: type: - string - 'null' enum: - belmont-research-center - di-rosa-sf - easterbrook-discovery-school - el-camino-road - richmond-field-station - san-ramon-phase-1 - yale-street - null sessionId: type: - string - 'null' pattern: >- ^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$ required: - eventId - finishedAt - runtimeVersion - cliVersion - kind - command - renderMode - renderProfile - sensors - frames - wallSeconds - gpuBusySeconds - outcome - errorCode - episodes - envSteps - map - sessionId additionalProperties: false minItems: 1 maxItems: 500 required: - schema - batchId - sealedAt - accountId - installId - machine - droppedEvents - events additionalProperties: false TelemetryBatchV2: type: object properties: schema: type: string enum: - simforge.usage-batch/v2 batchId: type: string pattern: >- ^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$ sealedAt: type: string pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$ accountId: type: string minLength: 1 maxLength: 128 installId: type: string pattern: >- ^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$ agreementVersion: type: string enum: - simforge-terms-draft-4 machine: type: object properties: os: type: string pattern: ^[a-z][a-z0-9-]{0,31}$ arch: type: string pattern: ^[a-z0-9_]{1,16}$ gpus: type: array items: type: object properties: model: type: string minLength: 1 maxLength: 128 pattern: ^[\x20-\x7e]+$ vramMib: type: - integer - 'null' minimum: 0 maximum: 1000000000000 driver: type: - string - 'null' maxLength: 64 pattern: ^[\x20-\x7e]*$ required: - model - vramMib - driver additionalProperties: false maxItems: 16 gpuCount: type: integer minimum: 0 maximum: 16 gpuProbe: type: string enum: - nvidia-smi - none required: - os - arch - gpus - gpuCount - gpuProbe additionalProperties: false droppedEvents: type: integer minimum: 0 maximum: 1000000000000 events: type: array items: type: object properties: eventId: type: string pattern: >- ^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$ finishedAt: type: string pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$ runtimeVersion: type: string pattern: ^[0-9A-Za-z.+-]{1,32}$ cliVersion: type: - string - 'null' pattern: ^[0-9A-Za-z.+-]{1,32}$ kind: type: string enum: - simulate - compile - render - preview - env - evaluate - transfer - export - command - cli - crash - session command: type: string pattern: ^[a-z][a-z0-9-]{0,31}$ renderMode: type: - string - 'null' enum: - 2d - schematic - 3d - null renderProfile: type: - string - 'null' enum: - training - showcase - schematic - null sensors: type: - integer - 'null' minimum: 0 maximum: 1000000000000 frames: type: - integer - 'null' minimum: 0 maximum: 1000000000000 wallSeconds: type: number minimum: 0 maximum: 100000000 gpuBusySeconds: type: - number - 'null' minimum: 0 maximum: 100000000 outcome: type: string enum: - ok - findings - error errorCode: type: - string - 'null' pattern: ^[a-z][a-z0-9_]{0,63}$ episodes: type: integer minimum: 0 maximum: 1000000000000 envSteps: type: integer minimum: 0 maximum: 1000000000000 map: type: - string - 'null' enum: - belmont-research-center - di-rosa-sf - easterbrook-discovery-school - el-camino-road - richmond-field-station - san-ramon-phase-1 - yale-street - null sessionId: type: - string - 'null' pattern: >- ^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$ cliCommand: type: - string - 'null' pattern: ^[a-z][a-z0-9-]{0,31}( [a-z][a-z0-9-]{0,31}){0,3}$ cliFlags: type: - array - 'null' items: type: string pattern: ^(--[a-z][a-z0-9-]{0,47}|-[A-Za-z])$ maxItems: 64 crashSite: type: - string - 'null' pattern: ^[0-9a-f]{16}$ rigPreset: type: - string - 'null' enum: - basic-dash-camera - tesla-hw3 - waymo-5th-gen - surround-7cam-1lidar - roof-8cam-6lidar-4radar - alpamayo-2cam - alpamayo-4cam - alpamayo-6cam - alpamayo-6cam-vqa - front-4cam-wide-cross-tele - physicalai-av-7cam - drone-fpv-forward - drone-inspection-wide-zoom - drone-inspection-wide - drone-mapping-nadir - custom - null resolution: type: - string - 'null' enum: - sd - hd - fhd - qhd - uhd - uhd-plus - null renderPasses: type: - array - 'null' items: type: string enum: - rgb - id - depth - semantic - instance - lidar - radar maxItems: 7 weather: type: - string - 'null' enum: - clear - cloudy - overcast - light_rain - heavy_rain - wet_road - fog_light - fog_dense - snow - sleet - custom - null timeOfDay: type: - string - 'null' enum: - dawn - morning - noon - afternoon - dusk - night - night_lit - custom - null datasetScenario: type: - string - 'null' pattern: ^[0-9a-f]{64}$ datasetVersion: type: - string - 'null' pattern: ^\d{1,6}\.\d{1,6}\.\d{1,6}$ agent: type: - string - 'null' enum: - claude-code - codex - cursor - other-agent - none - null cliSessionId: type: - string - 'null' pattern: >- ^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$ firstRun: type: - boolean - 'null' daysSinceInstall: type: - integer - 'null' minimum: 0 maximum: 100000 required: - eventId - finishedAt - runtimeVersion - cliVersion - kind - command - renderMode - renderProfile - sensors - frames - wallSeconds - gpuBusySeconds - outcome - errorCode - episodes - envSteps - map - sessionId - cliCommand - cliFlags - crashSite - rigPreset - resolution - renderPasses - weather - timeOfDay - datasetScenario - datasetVersion - agent - cliSessionId - firstRun - daysSinceInstall additionalProperties: false minItems: 1 maxItems: 500 required: - schema - batchId - sealedAt - accountId - installId - agreementVersion - machine - droppedEvents - events additionalProperties: false TelemetryReceipt: type: object properties: schema: type: string enum: - simforge.usage-receipt/v1 batchId: type: string pattern: >- ^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$ firstDelivery: type: boolean accepted: type: integer minimum: 0 required: - schema - batchId - firstDelivery - accepted 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 - recording_too_large - model_in_use - rate_limited - prompt_out_of_scope - relevance_check_unavailable - oracle_capacity_paused - cost_cap_exceeded - 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 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.