Roboflow Visual Search

Find visually similar image candidates in a Roboflow project.

Search a Roboflow project for images that look similar to an input image and return the nearest candidate plus metadata.

How This Block Works

This block uses the existing Roboflow project image search API:

1. Receives an input image from the workflow

2. Sends the image to Roboflow project search as image_base64

3. Requests useful fields such as image URL, tags, and user metadata

4. Returns the best candidate, best candidate image, metadata, tags, and the top candidates list

The target project should already contain uploaded images. Roboflow indexes those images for visual search using the platform's existing image indexing pipeline. This block does not create images, update metadata, or manage the index.

Type identifier

Use the following identifier in step "type" field: roboflow_core/visual_search@v1 to add the block as a step in your workflow.

Properties

Name	Type	Description	Refs
name	str	Enter a unique identifier for this step..	❌
workspace	str	Roboflow workspace URL slug that owns the target project..	✅
target_project	str	Roboflow project URL slug to search..	✅
top_k	int	Number of visually similar image candidates to return. Use 1 when you only need the nearest candidate..	✅

The Refs column marks possibility to parametrise the property with dynamic values available in workflow runtime. See Bindings for more info.

Runtime compatibility

requires_internet - air-gapped / offline deployments : This block depends on a service that is not reachable from fully offline / air-gapped deployments.

Input and Output Bindings

The available connections depend on its binding kinds. Check what binding kinds Roboflow Visual Search in version v1 has.

Input and output bindings

• input

  • image (image): Image to use as the visual search query..

  • workspace (string): Roboflow workspace URL slug that owns the target project..

  • target_project (roboflow_project): Roboflow project URL slug to search..

  • top_k (integer): Number of visually similar image candidates to return. Use 1 when you only need the nearest candidate..

• output

  • candidate_found (boolean): Boolean flag.

  • best_candidate (dictionary): Dictionary.

  • candidates (list_of_values): List of values of any type.

  • error_status (boolean): Boolean flag.

  • message (string): String value.

  • best_candidate_image (image): Image in workflows.

  • best_candidate_metadata (dictionary): Dictionary.

  • best_candidate_tags (list_of_values): List of values of any type.

Example JSON definition

{
	    "name": "<your_step_name_here>",
	    "type": "roboflow_core/visual_search@v1",
	    "image": "$inputs.image",
	    "workspace": "my-workspace",
	    "target_project": "reference-images",
	    "top_k": 1
	}