Roboflow Custom Metadata¶

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¶

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.

Available Connections¶

Input and Output Bindings¶

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

{
    "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
}