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:
Open the Versions page and create a new version
Follow our guide to get to the page that lets you create a dataset version.
Choose preprocessing steps
Select the preprocessing steps you need to train your model.
Apply augmentations
Apply any augmentations to your dataset. We have a guide that walks through which augmentations are appropriate for different use cases.
Confirm your Version
Your Version will be created and will now be available for use in training models.
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_KEYThis 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").modelThe 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-detectorID 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-01Get 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/3Export 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 yolov8JSON 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.