> For the complete documentation index, see [llms.txt](https://docs.roboflow.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.roboflow.com/workflows/blocks/blocks/advanced-blocks/roboflow-custom-metadata.md).

# 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:
   * Takes predictions from any supported model type (object detection, instance segmentation, keypoint detection, or classification)
   * Receives field name and field value for the custom metadata to attach
   * Accepts fire-and-forget flag for execution mode
2. Validates Roboflow API key:
   * Checks that a valid Roboflow API key is available (required for API access)
   * Raises an error if API key is missing with instructions on how to retrieve one
3. Extracts inference IDs from predictions:
   * For supervision Detections objects: extracts inference IDs from the data dictionary
   * For classification predictions: extracts inference ID from the prediction dictionary
   * Collects all unique inference IDs that need metadata attached
   * Handles cases where no inference IDs are found (returns error message)
4. Retrieves workspace information:
   * Gets workspace ID from Roboflow API using the provided API key
   * Uses caching (15-minute expiration) to avoid repeated API calls for workspace lookup
   * Caches workspace name using MD5 hash of API key as cache key
5. Adds custom metadata via API:
   * Calls Roboflow API to attach custom metadata field to each inference ID
   * Associates the field name and field value with the inference results
   * Metadata becomes available in the Model Monitoring dashboard for filtering and analysis
6. Executes synchronously or asynchronously:
   * **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
   * **Synchronous mode (fire\_and\_forget=False)**: Waits for API call to complete and returns immediate status, useful for debugging and error handling
7. Returns status information:
   * Outputs error\_status indicating success (False) or failure (True)
   * Outputs message with upload status or error details
   * 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@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..                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | ❌    |
| `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.

### :material-shield-half-full:{ style="color: #5e6c75" } Runtime compatibility

:material-cloud-off-outline:{ style="color: #546e7a" } `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 Custom Metadata` in version `v1` has.

<details>

<summary>Input and output bindings</summary>

* input
  * `predictions` (*Union\[*[*`object_detection_prediction`*](https://inference.roboflow.com/workflows/kinds/object_detection_prediction/)*,* [*`classification_prediction`*](https://inference.roboflow.com/workflows/kinds/classification_prediction/)*,* [*`instance_segmentation_prediction`*](https://inference.roboflow.com/workflows/kinds/instance_segmentation_prediction/)*,* [*`keypoint_detection_prediction`*](https://inference.roboflow.com/workflows/kinds/keypoint_detection_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`*](https://inference.roboflow.com/workflows/kinds/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`*](https://inference.roboflow.com/workflows/kinds/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`](https://inference.roboflow.com/workflows/kinds/boolean/)): Boolean flag.
  * `message` ([`string`](https://inference.roboflow.com/workflows/kinds/string/)): String value.

</details>

<details>

<summary>Example JSON definition</summary>

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

</details>