# Read or compute an immutable dataset-health report

`GET /v1/datasets/versions/{version_id}/health`

Return the persisted report, or run the bounded synchronous fallback.

- Base URL: `https://junction-api.qualiastudios.dev`
- Authentication: an API key in the `X-API-Key` header, or `Authorization: Bearer …`

## Parameters

- `version_id` (path, string (uuid), required)
- `account_id` (query, string | null (uuid)): Act on this account (active)

## Responses

- `200` Successful Response: `application/json` `DatasetHealthReportResponse`
- `401` Invalid or missing API key: `application/json` `ErrorResponse`
- `422` Validation Error: `application/json` `HTTPValidationError`

## Schemas

```yaml
DatasetHealthReportResponse:
  properties:
    contract:
      type: string
      const: qds.dataset-health.v1
    engine_revision:
      type: string
      maxLength: 128
      minLength: 1
    dataset_version_id:
      type: string
      format: uuid
    dataset_snapshot_id:
      type: string
      pattern: ^[0-9a-f]{64}$
    membership_hash:
      type: string
      pattern: ^[0-9a-f]{64}$
    norm_stats_hash:
      type: string
      pattern: ^[0-9a-f]{64}$
    member_count:
      type: integer
      maximum: 100000
      minimum: 1
    sampling:
      $ref: "#/components/schemas/DatasetHealthSamplingResponse"
    evidence_digest:
      type: string
      pattern: ^[0-9a-f]{64}$
    cache_identity:
      type: string
      pattern: ^[0-9a-f]{64}$
    health_score:
      maximum: 100
      minimum: 0
      type:
        - integer
        - "null"
    grade:
      nullable: true
      type: string
      enum:
        - A+
        - A
        - A-
        - B+
        - B
        - B-
        - C+
        - C
        - C-
        - D
        - F
    summary:
      maxLength: 4096
      type:
        - string
        - "null"
    metrics:
      $ref: "#/components/schemas/DatasetHealthNativeMetricsResponse"
    data_health:
      $ref: "#/components/schemas/DatasetHealthDiagnosticsResponse"
    flagged_episodes:
      items:
        $ref: "#/components/schemas/DatasetHealthFlaggedEpisodeResponse"
      type: array
      maxItems: 120
    recommendations:
      items:
        $ref: "#/components/schemas/DatasetHealthRecommendationResponse"
      type: array
      maxItems: 1
      minItems: 1
    evidence_completeness:
      $ref: "#/components/schemas/DatasetHealthEvidenceCompletenessResponse"
    report_digest:
      type: string
      pattern: ^[0-9a-f]{64}$
  additionalProperties: false
  type: object
  required:
    - contract
    - engine_revision
    - dataset_version_id
    - dataset_snapshot_id
    - membership_hash
    - norm_stats_hash
    - member_count
    - sampling
    - evidence_digest
    - cache_identity
    - health_score
    - grade
    - summary
    - metrics
    - data_health
    - flagged_episodes
    - recommendations
    - evidence_completeness
    - report_digest
  title: DatasetHealthReportResponse
  description: Canonical bounded report for one exact published DatasetVersion.
DatasetHealthSamplingResponse:
  properties:
    policy:
      type: string
      const: balanced-member-ordinal/1
    maximum_members:
      type: integer
      const: 120
    sampled_member_count:
      type: integer
      maximum: 120
      minimum: 1
    sampled_rows:
      type: integer
      maximum: 2000000
      minimum: 1
    sampled_ordinals:
      items:
        type: integer
      type: array
      maxItems: 120
      minItems: 1
    sampled_episode_revision_ids:
      items:
        type: string
      type: array
      maxItems: 120
      minItems: 1
  additionalProperties: false
  type: object
  required:
    - policy
    - maximum_members
    - sampled_member_count
    - sampled_rows
    - sampled_ordinals
    - sampled_episode_revision_ids
  title: DatasetHealthSamplingResponse
DatasetHealthNativeMetricsResponse:
  properties:
    motion_quality:
      $ref: "#/components/schemas/DatasetHealthMetricResponse"
    workspace_coverage:
      $ref: "#/components/schemas/DatasetHealthMetricResponse"
    data_integrity:
      $ref: "#/components/schemas/DatasetHealthMetricResponse"
  additionalProperties: false
  type: object
  required:
    - motion_quality
    - workspace_coverage
    - data_integrity
  title: DatasetHealthNativeMetricsResponse
DatasetHealthMetricResponse:
  properties:
    score:
      type: number
      maximum: 1
      minimum: 0
    details:
      $ref: "#/components/schemas/JsonValue"
  additionalProperties: false
  type: object
  required:
    - score
    - details
  title: DatasetHealthMetricResponse
  description: One bounded native metric over exact immutable trajectory bytes.
JsonValue: {}
DatasetHealthDiagnosticsResponse:
  properties:
    action_autocorrelation:
      $ref: "#/components/schemas/DatasetHealthMetricResponse"
    state_action_alignment:
      $ref: "#/components/schemas/DatasetHealthMetricResponse"
    demonstrator_speed_variance:
      $ref: "#/components/schemas/DatasetHealthMetricResponse"
    cross_episode_action_variance:
      $ref: "#/components/schemas/DatasetHealthMetricResponse"
    episode_smoothness:
      $ref: "#/components/schemas/DatasetHealthMetricResponse"
    sensor_health:
      $ref: "#/components/schemas/DatasetHealthMetricResponse"
    episode_pose_outliers:
      $ref: "#/components/schemas/DatasetHealthMetricResponse"
  additionalProperties: false
  type: object
  required:
    - action_autocorrelation
    - state_action_alignment
    - demonstrator_speed_variance
    - cross_episode_action_variance
    - episode_smoothness
    - sensor_health
    - episode_pose_outliers
  title: DatasetHealthDiagnosticsResponse
DatasetHealthFlaggedEpisodeResponse:
  properties:
    episode_revision_id:
      type: string
      pattern: ^[0-9a-f]{64}$
    member_ordinal:
      type: integer
      minimum: 0
    reasons:
      items:
        type: string
      type: array
      maxItems: 32
      minItems: 1
    severity:
      type: string
      enum:
        - low
        - medium
        - high
  additionalProperties: false
  type: object
  required:
    - episode_revision_id
    - member_ordinal
    - reasons
    - severity
  title: DatasetHealthFlaggedEpisodeResponse
DatasetHealthRecommendationResponse:
  properties:
    action:
      type: string
      enum:
        - none
        - review_episodes
    target:
      nullable: true
      items:
        type: string
      type: array
    impact:
      type: string
      maxLength: 4096
      minLength: 1
  additionalProperties: false
  type: object
  required:
    - action
    - target
    - impact
  title: DatasetHealthRecommendationResponse
DatasetHealthEvidenceCompletenessResponse:
  properties:
    native_trajectory_metrics:
      $ref: "#/components/schemas/DatasetHealthNativeEvidenceResponse"
    visual_diversity:
      $ref: "#/components/schemas/DatasetHealthUnavailableEvidenceResponse"
    demo_quality:
      $ref: "#/components/schemas/DatasetHealthUnavailableEvidenceResponse"
    trajectory_diversity:
      $ref: "#/components/schemas/DatasetHealthUnavailableEvidenceResponse"
    episode_outliers:
      $ref: "#/components/schemas/DatasetHealthUnavailableEvidenceResponse"
    behavioral_coverage:
      $ref: "#/components/schemas/DatasetHealthUnavailableEvidenceResponse"
    mutable_quality_projection:
      $ref: "#/components/schemas/DatasetHealthUnreadEvidenceResponse"
    mutable_review_projection:
      $ref: "#/components/schemas/DatasetHealthUnreadEvidenceResponse"
  additionalProperties: false
  type: object
  required:
    - native_trajectory_metrics
    - visual_diversity
    - demo_quality
    - trajectory_diversity
    - episode_outliers
    - behavioral_coverage
    - mutable_quality_projection
    - mutable_review_projection
  title: DatasetHealthEvidenceCompletenessResponse
DatasetHealthNativeEvidenceResponse:
  properties:
    status:
      type: string
      const: sampled_exact_immutable
    sample_policy:
      type: string
      const: balanced-member-ordinal/1
  additionalProperties: false
  type: object
  required:
    - status
    - sample_policy
  title: DatasetHealthNativeEvidenceResponse
DatasetHealthUnavailableEvidenceResponse:
  properties:
    status:
      type: string
      const: unavailable
    reason:
      type: string
      maxLength: 4096
      minLength: 1
  additionalProperties: false
  type: object
  required:
    - status
    - reason
  title: DatasetHealthUnavailableEvidenceResponse
DatasetHealthUnreadEvidenceResponse:
  properties:
    status:
      type: string
      const: not_read
  additionalProperties: false
  type: object
  required:
    - status
  title: DatasetHealthUnreadEvidenceResponse
ErrorResponse:
  properties:
    detail:
      type: string
      description: Error message describing what went wrong
  type: object
  required:
    - detail
  title: ErrorResponse
  description: Standard error response.
HTTPValidationError:
  properties:
    detail:
      items:
        $ref: "#/components/schemas/ValidationError"
      type: array
  type: object
  title: HTTPValidationError
ValidationError:
  properties:
    loc:
      items:
        type:
          - string
          - integer
      type: array
      title: Location
    msg:
      type: string
      title: Message
    type:
      type: string
      title: Error Type
    input: {}
    ctx:
      type: object
      title: Context
  type: object
  required:
    - loc
    - msg
    - type
  title: ValidationError
```