Skip to content

Roboflow Custom Metadata

Class: RoboflowCustomMetadataBlockV1

Source: inference.core.workflows.core_steps.sinks.roboflow.custom_metadata.v1.RoboflowCustomMetadataBlockV1

Attach custom metadata fields to inference results in the Roboflow Model Monitoring dashboard by extracting inference IDs from predictions and adding name-value pairs that enable filtering, analysis, and organization of inference data for monitoring workflows, production analytics, and model performance tracking.

How This Block Works

This block adds custom metadata to inference results stored in Roboflow Model Monitoring, allowing you to attach contextual information to predictions for filtering and analysis. The block:

  1. Receives model predictions and metadata configuration:
  2. Takes predictions from any supported model type (object detection, instance segmentation, keypoint detection, or classification)
  3. Receives field name and field value for the custom metadata to attach
  4. Accepts fire-and-forget flag for execution mode
  5. Validates Roboflow API key:
  6. Checks that a valid Roboflow API key is available (required for API access)
  7. Raises an error if API key is missing with instructions on how to retrieve one
  8. Extracts inference IDs from predictions:
  9. For supervision Detections objects: extracts inference IDs from the data dictionary
  10. For classification predictions: extracts inference ID from the prediction dictionary
  11. Collects all unique inference IDs that need metadata attached
  12. Handles cases where no inference IDs are found (returns error message)
  13. Retrieves workspace information:
  14. Gets workspace ID from Roboflow API using the provided API key
  15. Uses caching (15-minute expiration) to avoid repeated API calls for workspace lookup
  16. Caches workspace name using MD5 hash of API key as cache key
  17. Adds custom metadata via API:
  18. Calls Roboflow API to attach custom metadata field to each inference ID
  19. Associates the field name and field value with the inference results
  20. Metadata becomes available in the Model Monitoring dashboard for filtering and analysis
  21. Executes synchronously or asynchronously:
  22. Asynchronous mode (fire_and_forget=True): Submits task to background thread pool or FastAPI background tasks, allowing workflow to continue without waiting for API call to complete
  23. Synchronous mode (fire_and_forget=False): Waits for API call to complete and returns immediate status, useful for debugging and error handling
  24. Returns status information:
  25. Outputs error_status indicating success (False) or failure (True)
  26. Outputs message with upload status or error details
  27. Provides feedback on whether metadata was successfully attached

The block enables attaching custom metadata to inference results, making it easier to filter and analyze predictions in the Model Monitoring dashboard. For example, you can attach location labels, quality scores, processing flags, or any other contextual information that helps organize and analyze your inference data.

Common Use Cases

  • Location-Based Filtering: Attach location metadata to inferences for geographic analysis and filtering (e.g., tag inferences with location labels like "toronto", "warehouse_a", "production_line_1"), enabling location-based monitoring workflows
  • Quality Control Tagging: Attach quality or validation metadata to inferences for quality tracking (e.g., tag inferences as "pass", "fail", "requires_review", "approved"), enabling quality control workflows
  • Contextual Annotation: Add contextual information to inferences for better organization and analysis (e.g., tag with camera ID, time period, batch number, operator ID, environmental conditions), enabling contextual analysis workflows
  • Classification Enhancement: Attach custom labels or categories to inference results beyond model predictions (e.g., tag with business logic outcomes, workflow decisions, user feedback, manual corrections), enabling enhanced classification workflows
  • Production Analytics: Track production metrics by attaching metadata that represents operational context (e.g., tag with shift information, production batch, equipment status, performance metrics), enabling production analytics workflows
  • Filtering and Segmentation: Enable advanced filtering in Model Monitoring dashboard by attaching metadata that represents data segments (e.g., tag with customer segment, product category, use case type, deployment environment), enabling segmentation workflows

Connecting to Other Blocks

This block receives predictions and outputs status information:

  • After model blocks (Object Detection Model, Instance Segmentation Model, Classification Model, Keypoint Detection Model) to attach metadata to inference results (e.g., add location tags to detections, attach quality labels to classifications, tag keypoint detections with context), enabling model-to-metadata workflows
  • After filtering or analytics blocks (DetectionsFilter, ContinueIf, OverlapFilter) to tag filtered or analyzed results with metadata (e.g., tag filtered detections with filter criteria, attach analytics results as metadata, label processed results with workflow state), enabling analysis-to-metadata workflows
  • After conditional execution blocks (ContinueIf, Expression) to attach metadata based on workflow decisions (e.g., tag with decision outcomes, attach conditional branch labels, mark results based on conditions), enabling conditional-to-metadata workflows
  • In parallel with other sink blocks to combine metadata tagging with other data storage operations (e.g., tag while uploading to dataset, attach metadata while logging, combine with webhook notifications), enabling parallel sink workflows
  • Before or after visualization blocks to ensure metadata is attached before or after visualization operations (e.g., tag visualizations with context, attach metadata to visualized results), enabling visualization workflows with metadata
  • At workflow endpoints to ensure all inference results are tagged with metadata before workflow completion (e.g., final metadata attachment, comprehensive result tagging, complete metadata coverage), enabling end-to-end metadata workflows

Requirements

This block requires a valid Roboflow API key configured in the environment or workflow configuration. The API key is required to authenticate with Roboflow API and access Model Monitoring features. Visit https://docs.roboflow.com/api-reference/authentication#retrieve-an-api-key to learn how to retrieve an API key. The block requires predictions that contain inference IDs (predictions must have been generated by models that include inference IDs). Supported prediction types: object detection, instance segmentation, keypoint detection, and classification. The block uses workspace caching (15-minute expiration) to optimize API calls. For more information on Model Monitoring at Roboflow, see https://docs.roboflow.com/deploy/model-monitoring.

Type identifier

Use the following identifier in step "type" field: roboflow_core/roboflow_custom_metadata@v1to add the block as as step in your workflow.

Properties

Name Type Description Refs
name str Enter a unique identifier for this step.. ❌
field_name str Name of the custom metadata field to create in Roboflow Model Monitoring. This becomes the field name that can be used for filtering and analysis in the Model Monitoring dashboard. Field names should be descriptive and represent the type of metadata being attached (e.g., 'location', 'quality', 'camera_id', 'batch_number'). The field name is used to organize and categorize metadata values.. ❌
field_value str Value to assign to the custom metadata field. This is the actual data that will be attached to inference results and can be used for filtering and analysis in the Model Monitoring dashboard. Can be a string literal or a selector that references workflow outputs. Common values: location identifiers (e.g., 'toronto', 'warehouse_a'), quality labels (e.g., 'pass', 'fail', 'review'), identifiers (e.g., camera IDs, batch numbers), or any other contextual information relevant to your use case.. ✅
fire_and_forget bool Execution mode flag. When True (default), the block runs asynchronously in the background, allowing the workflow to continue processing without waiting for the API call to complete. This provides faster workflow execution but errors are not immediately available. When False, the block runs synchronously and waits for the API call to complete, returning immediate status and error information. Use False for debugging and error handling, True for production workflows where performance is prioritized.. ✅

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

Available Connections

Compatible Blocks

Check what blocks you can connect to Roboflow Custom Metadata in version v1.

Input and Output Bindings

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

Bindings

  • input

    • predictions (Union[object_detection_prediction, instance_segmentation_prediction, keypoint_detection_prediction, classification_prediction]): Model predictions (object detection, instance segmentation, keypoint detection, or classification) to attach custom metadata to. The predictions must contain inference IDs that are used to associate metadata with specific inference results in Roboflow Model Monitoring. Inference IDs are automatically extracted from supervision Detections objects or classification prediction dictionaries. The metadata will be attached to all inference IDs found in the predictions..
    • field_value (string): Value to assign to the custom metadata field. This is the actual data that will be attached to inference results and can be used for filtering and analysis in the Model Monitoring dashboard. Can be a string literal or a selector that references workflow outputs. Common values: location identifiers (e.g., 'toronto', 'warehouse_a'), quality labels (e.g., 'pass', 'fail', 'review'), identifiers (e.g., camera IDs, batch numbers), or any other contextual information relevant to your use case..
    • fire_and_forget (boolean): Execution mode flag. When True (default), the block runs asynchronously in the background, allowing the workflow to continue processing without waiting for the API call to complete. This provides faster workflow execution but errors are not immediately available. When False, the block runs synchronously and waits for the API call to complete, returning immediate status and error information. Use False for debugging and error handling, True for production workflows where performance is prioritized..

  • output

    • error_status (boolean): Boolean flag.
    • message (string): String value.
Example JSON definition of step Roboflow Custom Metadata in version v1 
{
    "name": "<your_step_name_here>",
    "type": "roboflow_core/roboflow_custom_metadata@v1",
    "predictions": "$steps.object_detection.predictions",
    "field_name": "location",
    "field_value": "toronto",
    "fire_and_forget": true
}