Dataset Iterations

GET/datasets/{dataset_id}/iterations

Retrieve the iteration history for a dataset, showing all refinement versions. This demonstrates the quality assurance process, including any discarded or superseded versions.

Path Parameters

Parameter	Type	Required	Description
`dataset_id`	string	Yes	Dataset ID (UUID)

Headers

Header	Required	Description
`Gerra-Api-Key`	Yes	Your API key

Example Request

curl "https://api.gerra.com/datasets/770e8400-e29b-41d4-a716-446655440000/iterations" \
  -H "Gerra-Api-Key: gerra_1234567890abcdef"

Response

{
  "iteration_group_id": "880e8400-e29b-41d4-a716-446655440000",
  "total_versions": 3,
  "latest_version": 2,
  "iterations": [
    {
      "dataset_id": "770e8400-e29b-41d4-a716-446655440000",
      "version": 0,
      "status": "superseded",
      "created_at": "2025-01-10T10:00:00Z",
      "prompt": "Person cooking breakfast in kitchen",
      "parent_dataset_id": null,
      "regeneration_reason": null,
      "superseded_reason": "Hand rendering artifacts",
      "preview_urls": {
        "gif": "https://storage.example.com/previews/v0.gif",
        "pose_frame": "https://storage.example.com/previews/v0_pose.jpg"
      },
      "download_url": "https://storage.example.com/datasets/v0.zip?token=...",
      "metadata": {
        "perspective": "pov",
        "duration_seconds": 5.0
      }
    },
    {
      "dataset_id": "880e8400-e29b-41d4-a716-446655440001",
      "version": 1,
      "status": "superseded",
      "created_at": "2025-01-12T14:30:00Z",
      "prompt": "Person cooking breakfast in kitchen, realistic hands",
      "parent_dataset_id": "770e8400-e29b-41d4-a716-446655440000",
      "regeneration_reason": "Hand rendering artifacts",
      "superseded_reason": "Background inconsistency",
      "preview_urls": {
        "gif": "https://storage.example.com/previews/v1.gif",
        "pose_frame": "https://storage.example.com/previews/v1_pose.jpg"
      },
      "download_url": "https://storage.example.com/datasets/v1.zip?token=...",
      "metadata": {
        "perspective": "pov",
        "duration_seconds": 5.0
      }
    },
    {
      "dataset_id": "990e8400-e29b-41d4-a716-446655440002",
      "version": 2,
      "status": "pending",
      "created_at": "2025-01-15T09:15:00Z",
      "prompt": "Person cooking breakfast in modern kitchen, realistic hands, consistent background",
      "parent_dataset_id": "880e8400-e29b-41d4-a716-446655440001",
      "regeneration_reason": "Background inconsistency",
      "superseded_reason": null,
      "preview_urls": {
        "gif": "https://storage.example.com/previews/v2.gif",
        "pose_frame": "https://storage.example.com/previews/v2_pose.jpg"
      },
      "download_url": "https://storage.example.com/datasets/v2.zip?token=...",
      "metadata": {
        "perspective": "pov",
        "duration_seconds": 5.0
      }
    }
  ]
}

Response Fields

Field	Type	Description
`iteration_group_id`	string	Shared ID across all versions
`total_versions`	integer	Total number of versions
`latest_version`	integer	Most recent version number
`iterations`	array	List of all iteration versions

Iteration Item Fields

Field	Type	Description
`dataset_id`	string	Unique ID for this version
`version`	integer	Version number (0, 1, 2, ...)
`status`	string	Current status
`created_at`	string	ISO 8601 creation timestamp
`prompt`	string	Generation prompt used
`parent_dataset_id`	string	Previous version's ID (null for v0)
`regeneration_reason`	string	Why this version was created
`superseded_reason`	string	Why this version was replaced
`preview_urls`	object	Pre-signed URLs for preview assets
`download_url`	string	Pre-signed download URL
`metadata`	object	Dataset metadata

Understanding Iterations

Iterations show the refinement process for synthetic datasets:

v0: Original generation
v1, v2, ...: Refined versions based on feedback
Only the latest version with status pending, accepted, or rejected is active
Previous versions are marked as superseded with a reason

This transparency helps you understand the quality assurance process and see what improvements were made.

Error Responses

Status	Description
`401`	Missing or invalid `Gerra-Api-Key` header
`403`	Dataset does not belong to your organization
`404`	Dataset not found or no iterations available

Dataset Iterations

On this page