Image Metadata
Attach custom key-value metadata to images so you can search, filter, and organize your dataset.
Metadata lets you attach custom key-value pairs to images in your Roboflow workspace. Use metadata to store structured information alongside your images - such as capture conditions, device identifiers, quality scores, or any domain-specific attributes - and then search, filter, and organize your data around those attributes.
Overview
Each image can hold any number of metadata entries. An entry is a key (a name like camera_id) paired with a value (a string, number, or boolean).
String
location: "warehouse-3", shift: "night"
Number
temperature: 72.5, quality_score: 95
Boolean
reviewed: true, is_night: false
Use cases
Capture context - record camera ID, GPS coordinates, weather, lighting conditions
Quality tracking - attach confidence scores, review status, annotator IDs
Data slicing - filter your dataset by any attribute to build targeted training sets
External system linking - store identifiers that connect images back to your internal tools
Adding Metadata
You can add metadata to images through the web UI, the Python SDK, the CLI, the HTTP API, or automatically via S3 Bucket Mirror.
Web Application
Values are automatically parsed by type:
front
"front" (string)
95
95 (number)
3.14
3.14 (number)
true / false
true / false (boolean)

Python SDK
Pass a metadata dictionary when uploading an image:
CLI
Use the roboflow image metadata command to update metadata and tags on existing images:
A single image ID updates synchronously. Multiple comma-separated IDs (up to 1,000) use the batch async endpoint. Add --poll to wait for the batch to finish; without it the command returns a taskId you can check later with roboflow asynctasks get <task-id>.
-m, --metadata
JSON string of key-value pairs to set
--remove-metadata
Comma-separated metadata keys to remove
--tags
Comma-separated tags to add
--remove-tags
Comma-separated tags to remove
--poll / --no-poll
Wait for batch completion (batch mode only)
--timeout
Polling timeout in seconds (default: 1800)
HTTP API
To add metadata as you upload an image, send a metadata field with a JSON object string in the multipart form, or as a query parameter.
Adds an image to the project and puts it in a batch. Send the image as a multipart file or a base64 body, or pass the image query parameter to have Roboflow fetch it from a URL. Uploading an image the project already has returns the existing image ID with duplicate set to true. Requires image:create. /{workspace}/{project}/upload works the same way.
Roboflow API key or OAuth access token.
Project URL slug.
URL of an image for Roboflow to fetch and add. URL-encode it. Use it when you do not send the image in the body.
https://i.imgur.com/PEEvqPN.pngFile name of the image. Roboflow infers it when you leave it out.
dock-cam-001.jpgSplit the image goes to.
trainPossible values: Name of the batch to add the image to. Without it, the image goes to the "Uploaded via API" batch.
Warehouse camsNote for the batch. The batch keeps the first note it gets. Annotation jobs made from the batch use it as their default instructions.
Label every forklift, even when it is partly hidden.Tag to add to the image. Repeat it to add more tags.
nightCustom metadata as a JSON object string. Keys use letters, numbers, underscores, and dots, and do not start with a dot. Keys that start with rf_internal are reserved.
{"camera_id":"cam001"}Position of the image in a sequence. Use it to keep images in order.
Total number of images in the sequence.
100000Inference ID from a Roboflow prediction. It links the image to that prediction in Model Monitoring.
The whole body is the image encoded as base64. A data URL prefix (ex: data:image/jpeg;base64,) is allowed. Send every option as a query parameter.
Successful response.
True when Roboflow added a new image.
True when the project already has this exact image. No new image is added, and id is the existing image.
Image ID. Use it to upload an annotation for the image.
No image was sent, the image is too large or not readable, metadata or notes is invalid, or Roboflow could not fetch the image URL (bad URL, private address, or a 4xx answer from the host). A failed fetch has a message that starts with "Could not fetch image URL".
Authentication is missing or invalid.
The credential does not have access to this resource.
The resource does not exist or is not accessible.
The request rate is too high.
The host of the image URL answered with a 5xx status or the connection failed. The response sets retryable to true, so send the same request again later.
POST /dataset/{project}/upload HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: multipart/form-data
Accept: */*
Content-Length: 134
{
"file": "binary",
"name": "dock-cam-001.jpg",
"split": "train",
"tag": "night",
"metadata": "{\"camera_id\":\"cam001\",\"temperature\":72.5}"
}{
"success": true,
"id": "YbNIgavTIk2xOOmJsHv5"
}To change metadata and tags on an image that is already in your workspace, update one image right away:
Sets and removes custom metadata and tags on one image, right away. The image can be in any project of the workspace. Requires image:tag.
Roboflow API key or OAuth access token.
Workspace URL slug.
Image ID.
Send at least one field. A key or tag cannot be both set and removed in one request. Keys use letters, numbers, underscores, and dots, and do not start with a dot. Keys that start with rf_internal are reserved.
Metadata keys to delete.
Tags to add.
Tags to remove.
Successful response.
The body is empty, a field has the wrong type, a key or tag is invalid, or the same key or tag is both set and removed.
Authentication is missing or invalid.
The credential does not have access to this resource.
The image does not exist or belongs to another workspace.
The request rate is too high.
POST /{workspace}/images/{imageId}/metadata HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 71
{
"metadata": {
"camera": "front",
"blur_score": 0.8
},
"addTags": [
"reviewed"
]
}{
"success": true
}Or update up to 1,000 images in the background, then poll the returned task URL with the Async Tasks API:
Sets and removes custom metadata and tags on up to 1,000 images in the background. Poll the returned task URL until it finishes. An image that is missing or in another workspace fails on its own and does not stop the others. Requires image:tag.
Roboflow API key or OAuth access token.
Workspace URL slug.
Accepted for asynchronous processing.
Asynchronous task ID.
URL to poll for the task status. The finished task's result lists totalProcessed, succeeded, failed, and failedItems.
updates is empty or has more than 1,000 entries, an image ID is listed twice, or an entry is invalid.
Authentication is missing or invalid.
The credential does not have access to this resource.
The resource does not exist or is not accessible.
The request rate is too high.
POST /{workspace}/images/metadata HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 138
{
"updates": [
{
"imageId": "abc123",
"metadata": {
"camera": "front"
},
"addTags": [
"reviewed"
]
},
{
"imageId": "def456",
"removeTags": [
"needs-review"
]
}
]
}{
"taskId": "Qm9yZWFsVGFzazEyMw",
"url": "https://api.roboflow.com/my-workspace/asynctasks/Qm9yZWFsVGFzazEyMw"
}S3 Bucket Mirror
When using Datasources to sync images from an S3 bucket, metadata is imported via JSON sidecar files placed alongside each image. See Datasources for sidecar file format, constraints, and update strategies.
MCP Server
Connect your AI agent to the MCP Server and it can tag images and set metadata on them with these tools:
images_update_metadata
Update metadata and tags on a single image.
images_batch_update_metadata
Batch-update metadata and tags on multiple images.
images_search
Find the images you want to update, by tag, class, or metadata.
Searching by Metadata
Metadata is indexed and searchable in the Asset Library. Use the search bar to filter images by metadata values:
You can combine metadata filters with other search filters:
The Asset Library also provides autocomplete for metadata keys and values based on what exists in your workspace.
Key Naming Rules
Metadata keys must follow these rules:
Allowed characters
Letters (a-z, A-Z), numbers (0-9), underscores (_), dots (.)
First character
Must be a letter, number, or underscore
Forbidden characters
Forward slashes (/) are not allowed
Valid keys: camera_id, capture.temperature, _internal_ref, v2_score
Invalid keys: camera/id (contains /), .starts_with_dot (starts with .), has spaces (contains spaces)
Metadata vs. Tags
Both metadata and tags help you organize images, but they serve different purposes:
Structure
Simple labels
Key-value pairs
Values
No value, just a name
String, number, or boolean
Best for
Categorization, workflow status
Structured attributes, measurements
Example
reviewed, v2, needs-annotation
temperature: 72.5, camera_id: "cam001"
You can use both on the same image. For example, tag an image as reviewed and also store reviewer: "alice" and confidence: 0.95 as metadata.
Last updated
Was this helpful?