Dataset Versions

Create dataset versions as point-in-time snapshots with preprocessing and augmentation before training.

About

Versions are point-in-time snapshots of the images and labels in your dataset. When you create a Version, you can apply preprocessing steps and augmentations to your dataset.

To train a model in Roboflow, you need to create a Dataset Version.

This section of our documentation walks through how to prepare to train a model. You will need to:

1

Open the Versions page and create a new version

Follow our guide to get to the page that lets you create a dataset version.

2

Choose preprocessing steps

Select the preprocessing steps you need to train your model.

3

Apply augmentations

Apply any augmentations to your dataset. We have a guide that walks through which augmentations are appropriate for different use cases.

4

Confirm your Version

Your Version will be created and will now be available for use in training models.

5

Train a model

Follow our model training documentation to configure your training job.

You can also export a dataset version.

HTTP API

View a Version

You can retrieve information about a Roboflow version using the Python SDK, REST API, and CLI.

Version ID

Each version generated in Roboflow has a sequential, numerical ID associated with it. You can see that through the app on your versions page or by listing your project versions in the API.

If you already know which project and version you want to retrieve information about, you can use the /:workspace/:project/:version endpoint. It returns similar information as the project endpoint but does not enumerate all of the project's other versions.

To retrieve information about a project, make a GET request to the following endpoint:

https://api.roboflow.com/roboflow/chess-sample-4ckfl/1?api_key=$ROBOFLOW_API_KEY

This endpoint returns the following response:

{
    "workspace": {
        "name": "Roboflow",
        "url": "roboflow",
        "members": 7
    },
    "project": {
        "id": "roboflow/chess-sample-4ckfl",
        "type": "object-detection",
        "name": "Chess Sample",
        "created": 1630335544.592,
        "updated": 1630335741.988,
        "images": 12,
        "unannotated": 3,
        "annotation": "pieces",
        "public": false,
        "splits": {
            "test": 1,
            "valid": 2,
            "train": 9
        },
        "classes": {
            "black-knight": 11,
            "black-queen": 4,
            "black-king": 8,
            "white-king": 8,
            "white-pawn": 34,
            "black-bishop": 8,
            "white-rook": 10,
            "black-pawn": 37,
            "white-knight": 10,
            "white-bishop": 11,
            "black-rook": 10,
            "white-queen": 7
        }
    },
    "version": {
        "id": "roboflow/chess-sample-4ckfl/1",
        "name": "augmented",
        "created": 1630335698.746,
        "images": 30,
        "splits": {
            "valid": 2,
            "test": 1,
            "train": 27
        },
        "model": {
            "id": "chess-sample-4ckfl/1",
            "endpoint": "https://serverless.roboflow.com/infer/chess-sample-4ckfl/1",
            "start": 1630335799.682,
            "end": 1630337523.889,
            "fromScratch": false,
            "tfjs": true,
            "oak": true,
            "map": "62.87",
            "recall": "85.29",
            "precision": "23.44"
        },
        "preprocessing": {
            "resize": {
                "height": 416,
                "width": 416,
                "format": "Stretch to",
                "enabled": true
            },
            "auto-orient": {
                "enabled": true
            },
            "grayscale": {
                "enabled": true
            }
        },
        "augmentation": {
            "rotate": {
                "degrees": "5",
                "enabled": true
            },
            "brightness": {
                "darken": true,
                "enabled": true,
                "brighten": true,
                "percent": "25"
            },
            "noise": {
                "percent": "2",
                "enabled": true
            },
            "crop": {
                "enabled": true,
                "min": 0,
                "percent": 30
            },
            "flip": {
                "horizontal": true,
                "vertical": false,
                "enabled": true
            },
            "image": {
                "versions": "3",
                "enabled": true
            },
            "exposure": {
                "enabled": true,
                "percent": "25"
            }
        },
        "exports": [
            "yolov5pytorch"
        ],
        "train": {
            "status": "finished",
            "results": {
                "class_map": {
                    "valid": [
                        {
                            "images": "20",
                            "map95": "0.29",
                            "precision": "0.795",
                            "recall": "0.48",
                            "map50": "0.547",
                            "class": "all",
                            "targets": "82"
                        },
                        ...
                    ],
                    "test": [
                        {
                            "images": "10",
                            "map95": "0.478",
                            "precision": "0.846",
                            "recall": "0.759",
                            "map50": "0.844",
                            "class": "all",
                            "targets": "29"
                        },
                        ...
                    ]
                }
            }
        },
        "models": {
            "roboflow-train": {
                "epochs": [
                    {
                        "mAP": "0.5624740875589795",
                        "epoch": "0",
                        "precision": "0.848007354583702",
                        "recall": "0.4796292117720689",
                        "box_loss": "0.04430354",
                        "obj_loss": "0.023823218",
                        "class_loss": "0.012277425",
                        "mAP_50_95": "0.3004394102727502"
                    },
                    {
                        "mAP": "0.5576528999996365",
                        "epoch": "1",
                        "precision": "0.8477760345230224",
                        "recall": "0.47967238365789094",
                        "box_loss": "0.041422606",
                        "obj_loss": "0.020020777",
                        "class_loss": "0.010422977",
                        "mAP_50_95": "0.2943194093111112"
                    },
                    ...
                ]
            }
        },
        "classes": [
            "black-knight",
            "black-queen",
            "black-king",
            "white-king",
            "white-pawn",
            "black-bishop",
            "white-rook",
            "black-pawn",
            "white-knight",
            "white-bishop",
            "black-rook",
            "white-queen"
        ]
    }
}

Keypoint Detection Skeletons

Keypoint Detection project versions will contain a skeletons field which contains your version skeletons for each class. For example, a project with a class person might have the following skeleton:

{
...
"skeletons": {
    "person": {
        "vertices": [
            {
                "color": "#FF8000",
                "id": 0,
                "name": "nose",
                "x": 0.4546,
                "y": 0.18859999999999996
            },
            {
                "color": "#FF00FF",
                "id": 1,
                "name": "left_eye"
                "x": 0.478,
                "y": 0.1606
            },
            ...
        ],
        "edges": [
            {
                "color": "#00FFCE",
                "from": 13,
                "to": 15
            },
            ...
        ],
        "symmetries": [
            {
                "direction": "horizontal",
                "points": [1, 2]
            },
            ...
        ]
    }
}

Note, vertices should be accessed by index with inference predictions class_id. Then, vertex id can be used to reference edge (from/to) and symmetries (points).

Python SDK

View a Version

To retrieve information about a version, get the project and request the version you want:

import roboflow

rf = roboflow.Roboflow(api_key="YOUR_API_KEY")

# get a project
project = rf.workspace().project("PROJECT_ID")

model = project.version("1").model

The model variable contains the following JSON values:

{
  "id": "mug-detector-eocwp/12",
  "name": "Mug Detector",
  "version": "12",
  "classes": null,
  "overlap": 30,
  "confidence": 40,
  "stroke": 1,
  "labels": false,
  "format": "json",
  "base_url": "https://serverless.roboflow.com/infer/"
}

For listing and iterating over versions, see List Workspaces and Projects. To export a version, see Export a Dataset Version.

CLI

You can list, inspect, and export dataset versions from the command line.

List Versions

roboflow version list -p <project>

Example:

roboflow version list -p my-detector

ID                              NAME              IMAGES  CREATED
my-workspace/my-detector/1      raw               100     2024-01-15
my-workspace/my-detector/2      augmented-640     300     2024-01-20
my-workspace/my-detector/3      augmented-416     250     2024-02-01

Get Version Details

roboflow version get -p <project> <version-number>

Or use resource shorthand:

roboflow version get my-detector/3
roboflow version get my-workspace/my-detector/3

Export a Version

Trigger an async export of a version in a specific format:

roboflow version export -p <project> <version-number> -f <format>

Example:

roboflow version export -p my-detector 3 -f yolov8

JSON Output

All version commands support --json:

roboflow version list -p my-detector --json

[
  {
    "id": "my-workspace/my-detector/1",
    "name": "raw",
    "images": 100,
    "created": "2024-01-15T00:00:00"
  }
]

MCP Server

Connect your AI agent to the MCP Server and it can manage dataset versions with these tools:

Tool	Description
versions_generate	Create a version with optional preprocessing and augmentation.
versions_get	Get version info including splits and its trainings.
versions_export	Check or trigger a dataset export for a version.
versions_delete	Delete a version, moving it to the workspace Trash.

Next steps

• Use your version to train a model. See Train a Model.

• Export your version in a training-ready format. See Export a Dataset Version.