> ## 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. # List a dataset's files > A dataset, a filter of it or chosen scenarios as files (simforge.dataset-files/v1): signed links to the stored objects, a page at a time; `format=urls` for an aria2c link list; `dryRun` for counts and size. Files still being prepared are `pending`: ask for the same page again. ## OpenAPI ````yaml /api-reference/openapi.json get /api/v1/datasets/{id}/files 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/datasets/{id}/files: get: tags: - Datasets summary: List a dataset's files description: >- A dataset, a filter of it or chosen scenarios as files (simforge.dataset-files/v1): signed links to the stored objects, a page at a time; `format=urls` for an aria2c link list; `dryRun` for counts and size. Files still being prepared are `pending`: ask for the same page again. operationId: listDatasetFiles parameters: - in: path name: id required: true schema: type: string - in: query name: q required: false schema: type: string description: Free-text search, as in the library's search box. - in: query name: filter required: false schema: type: string description: >- Library filters: space-separated `facet:value[,value]` tokens, e.g. `grade:A tag:cut-in`. - in: query name: sourceLog required: false schema: type: string description: Only the scenarios of one recorded drive. - in: query name: ids required: false schema: type: string description: >- Exactly these scenarios, comma-separated document ids (POST the same fields for long lists). - in: query name: include required: false schema: type: string description: >- Comma-separated: `renders[:training|showcase|schematic]`, `labels`, `gt`, `recordings`, or `scenarios` alone; default `renders:training`. - in: query name: passes required: false schema: type: string description: Keep only these render modalities (comma-separated). - in: query name: cursor required: false schema: type: string minLength: 1 - in: query name: limit required: false schema: type: integer minimum: 1 maximum: 1000 - in: query name: format required: false schema: type: string enum: - json - urls description: >- `urls`: the whole selection as an aria2c input file of 24-hour links. - in: query name: dryRun required: false schema: type: boolean description: Counts and size of the whole selection; no links. responses: '200': description: >- A page of files (each a signed GET of the stored object, range-capable; ask again for fresh links), the dry-run summary, or (`format=urls`) the link list. content: application/json: schema: oneOf: - $ref: '#/components/schemas/DatasetFilesPage' - $ref: '#/components/schemas/DatasetFilesSummary' text/plain: schema: type: string '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' '404': description: The request failed. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '429': description: >- `rate_limited`: too many requests this minute; `Retry-After` says when to ask again. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' security: - simforgeToken: - datasets:read - artifacts:read components: schemas: DatasetFilesPage: type: object properties: schema: type: string enum: - simforge.dataset-files/v1 dataset: $ref: '#/components/schemas/DatasetFilesDataset' selection: $ref: '#/components/schemas/DatasetFilesSelection' include: $ref: '#/components/schemas/DatasetFilesInclude' scenarios: type: array items: $ref: '#/components/schemas/DatasetFilesScenario' description: This page's scenarios.jsonl rows, by document id. files: type: array items: $ref: '#/components/schemas/DatasetFile' description: Every file of this page's scenarios, and the recordings they bring. excluded: type: array items: $ref: '#/components/schemas/DatasetFilesExclusion' nextCursor: type: - string - 'null' required: - schema - dataset - selection - include - scenarios - files - excluded - nextCursor DatasetFilesSummary: type: object properties: dryRun: type: boolean enum: - true schema: type: string enum: - simforge.dataset-files/v1 dataset: $ref: '#/components/schemas/DatasetFilesDataset' selection: $ref: '#/components/schemas/DatasetFilesSelection' include: $ref: '#/components/schemas/DatasetFilesInclude' counts: $ref: '#/components/schemas/DatasetFilesCounts' excluded: type: array items: $ref: '#/components/schemas/DatasetFilesExclusion' description: The first 100 exclusions. required: - dryRun - schema - dataset - selection - include - counts - excluded 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 DatasetFilesDataset: type: object properties: id: type: string name: type: string required: - id - name DatasetFilesSelection: oneOf: - $ref: '#/components/schemas/DatasetFilesWholeDataset' - $ref: '#/components/schemas/DatasetFilesFiltered' - $ref: '#/components/schemas/DatasetFilesDocuments' discriminator: propertyName: kind mapping: dataset: '#/components/schemas/DatasetFilesWholeDataset' query: '#/components/schemas/DatasetFilesFiltered' documents: '#/components/schemas/DatasetFilesDocuments' DatasetFilesInclude: type: object properties: renders: $ref: '#/components/schemas/DatasetFilesRenders' labels: type: boolean groundTruth: type: boolean recordings: type: boolean generated: type: boolean description: >- The scenarios' accepted and flagged SimForge Factory clips, under `generated/-/`. required: - renders - labels - groundTruth - recordings - generated DatasetFilesScenario: type: object properties: id: type: string revisionId: type: string title: type: string dir: type: string map: $ref: '#/components/schemas/DatasetFilesMap' grade: type: - object - 'null' properties: tier: type: string basis: type: - string - 'null' required: - tier - basis tags: type: array items: type: string split: type: string lineage: $ref: '#/components/schemas/DatasetFilesLineage' licence: type: - string - 'null' simulation: type: object properties: simKey: type: string engineSemVer: type: string resolvedInputDigest: type: string required: - simKey - engineSemVer - resolvedInputDigest recording: type: - string - 'null' description: The source drive, when `recordings` is included. recordings: type: array items: type: string description: >- The recordings the document pins (always pulled: the document replays them). renders: type: array items: $ref: '#/components/schemas/DatasetFilesRender' generated: type: array items: $ref: '#/components/schemas/DatasetFilesGenerated' description: Its Factory clips, when `generated` is included. members: type: array items: $ref: '#/components/schemas/DatasetFilesMember' required: - id - revisionId - title - dir - map - grade - tags - split - lineage - licence - simulation - recording - recordings - renders - generated - members DatasetFile: type: object properties: path: type: string description: Where the file goes in the pulled folder (relative, `/`-separated). role: type: string enum: - document - openscenario - trace - resolution - labels - gt-ego - gt-actors - recording - render - generated mediaType: type: string state: type: string enum: - ready - pending description: >- `pending`: still being prepared (no digest, size or URL yet); ask for the same page again. sha256: type: - string - 'null' pattern: ^[a-f0-9]{64}$ size: type: - integer - 'null' minimum: 0 url: type: - string - 'null' description: >- A signed GET of the stored object; it supports HTTP range requests. Ask for the page again for a fresh one. urlExpiresAt: type: - string - 'null' documentId: type: - string - 'null' description: >- The scenario it belongs to; null for a recording several scenarios share. required: - path - role - mediaType - state - sha256 - size - url - urlExpiresAt - documentId DatasetFilesExclusion: type: object properties: documentId: type: string title: type: string code: type: string reason: type: string path: type: - string - 'null' description: >- The file that cannot be produced; null when the whole scenario is left out. required: - documentId - title - code - reason - path DatasetFilesCounts: type: object properties: scenarios: type: integer minimum: 0 files: type: integer minimum: 0 bytes: type: number minimum: 0 description: The bytes of every file whose size is known. pendingFiles: type: integer minimum: 0 description: Files not prepared yet; sized when they are first listed. renders: type: integer minimum: 0 generated: type: integer minimum: 0 description: Factory clips. recordings: type: integer minimum: 0 excluded: type: integer minimum: 0 required: - scenarios - files - bytes - pendingFiles - renders - generated - recordings - excluded DatasetFilesWholeDataset: type: object properties: kind: type: string enum: - dataset required: - kind DatasetFilesFiltered: type: object properties: kind: type: string enum: - query query: $ref: '#/components/schemas/DatasetFilesQuery' required: - kind - query DatasetFilesDocuments: type: object properties: kind: type: string enum: - documents documentIds: type: array items: type: string required: - kind - documentIds DatasetFilesRenders: type: object properties: presets: type: array items: type: string enum: - training - showcase - schematic modalities: type: - array - 'null' items: type: string enum: - rgb - depth - semantic - instance - lidar - radar required: - presets - modalities DatasetFilesMap: type: object properties: versionId: type: string name: type: - string - 'null' sourceMapId: type: - string - 'null' xodrSha256: type: - string - 'null' required: - versionId - name - sourceMapId - xodrSha256 DatasetFilesLineage: type: object properties: derivationKind: type: - string - 'null' parentId: type: - string - 'null' sourceRecordingSha256: type: - string - 'null' source: type: - object - 'null' properties: dataset: type: - string - 'null' logId: type: - string - 'null' label: type: - string - 'null' required: - dataset - logId - label required: - derivationKind - parentId - sourceRecordingSha256 - source DatasetFilesRender: type: object properties: id: type: string preset: type: string enum: - training - showcase - schematic engine: type: string source: type: string enum: - studio - cloud dir: type: string files: type: array items: $ref: '#/components/schemas/DatasetFilesRenderFile' required: - id - preset - engine - source - dir - files DatasetFilesGenerated: type: object properties: dir: type: string description: '`/generated/-`.' runId: type: string description: >- The Factory run that made it; when two runs made the same folder, the newest. lookId: type: string seed: type: integer minimum: 0 verdict: type: string enum: - accepted - flagged description: The clip check's verdict; a rejected clip is never delivered. files: type: array items: $ref: '#/components/schemas/DatasetFilesGeneratedFile' description: >- Every file of the clip, `manifest.json` and `quality.json` among them. required: - dir - runId - lookId - seed - verdict - files DatasetFilesMember: type: object properties: path: type: string role: type: string enum: - document - openscenario - trace - resolution - labels - gt-ego - gt-actors sha256: type: - string - 'null' pattern: ^[a-f0-9]{64}$ size: type: - integer - 'null' minimum: 0 required: - path - role - sha256 - size DatasetFilesQuery: type: object properties: q: type: string filters: type: object additionalProperties: type: array items: type: string sourceLogId: type: - string - 'null' required: - q - filters - sourceLogId DatasetFilesRenderFile: type: object properties: path: type: string sha256: type: string pattern: ^[a-f0-9]{64}$ size: type: integer minimum: 0 role: type: string mediaType: type: string sensorId: type: - string - 'null' actorId: type: - string - 'null' modality: type: - string - 'null' required: - path - sha256 - size - role - mediaType - sensorId - actorId - modality DatasetFilesGeneratedFile: type: object properties: path: type: string sha256: type: string pattern: ^[a-f0-9]{64}$ size: type: integer minimum: 0 mediaType: type: string required: - path - sha256 - size - mediaType 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.