> 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/data-storage/roboflow-vision-events.md). # Roboflow Vision Events Send images, model predictions, and event metadata to the Roboflow Vision Events API for monitoring, quality control, safety alerting, and custom event tracking. ## How This Block Works This block uploads workflow images and model predictions to the Roboflow Vision Events API, creating structured events that can be queried, filtered, and visualized in the Roboflow dashboard. 1. Optionally uploads an input image and/or output image (visualization) to the Vision Events image storage via the public API 2. Converts model predictions (object detection, classification, instance segmentation, or keypoint detection) into the Vision Events annotation format and attaches them to the input image 3. Creates a vision event with the specified event type, use case, event data, and custom metadata 4. Enforces a built-in rate limit (`cooldown_seconds`, default 1 second) so high-frequency video workflows do not flood the API with an event per frame 5. Supports fire-and-forget mode for non-blocking execution ## Rate Limiting Video workflows can run many times per second, which by default would send an event (and its images) for every frame. To prevent this, the block enforces a cooldown between consecutive events: at most one event per second is sent by default. Events triggered during the cooldown period are dropped and the `throttling_status` output is set to `True`. Adjust `cooldown_seconds` to your needs, or set it to `0` to disable rate limiting entirely (e.g. for intentionally bursty use cases). The cooldown timer lives in the block instance, so it throttles long-lived executions such as persistent WebRTC sessions. Workflows served over HTTP (ex: `/workflows/run`) create fresh block instances per request, so the cooldown does not throttle across separate HTTP calls. ## Deployment Modes By default this block sends events to the **Roboflow Vision Events API** (cloud / Serverless API), uploading images and posting the event over the public API. For edge deployments, enable **Write to Local Event Store** to send events to a local Event Ingestion Service instead. In this mode images are embedded directly in the request (no upload step) and the event is posted to `/v2/events`. The event store URL defaults to `http://localhost:8001` and can be overridden. No Roboflow API key is required in this mode; if the local service requires authentication, set the `EVENT_INGESTION_API_KEY` environment variable on the inference server. ## Event Types * **quality\_check**: Manufacturing/inspection QA with pass/fail result and optional confidence * **inventory\_count**: Inventory tracking with location, item count, and item type * **safety\_alert**: Safety violations with alert type, severity (low/medium/high), and description * **custom**: User-defined events with a free-form value string * **operator\_feedback**: Operator review/correction of previous events (correct/incorrect/inconclusive) ## Requirements The default (cloud) mode requires a valid Roboflow API key with `vision-events:write` scope, configured in your environment or workflow configuration. No Roboflow API key is needed when **Write to Local Event Store** is enabled (see Deployment Modes above). ## Common Use Cases * **Quality Control**: Automatically log inspection results with images and detection overlays * **Safety Monitoring**: Send safety alerts when violations are detected in video streams * **Production Analytics**: Track inventory counts and production metrics with visual evidence * **Active Monitoring**: Fire-and-forget event logging from real-time video processing workflows ### Type identifier Use the following identifier in step `"type"` field: `roboflow_core/roboflow_vision_events@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.. | ❌ | | `event_type` | `str` | The type of vision event to create.. | ✅ | | `solution` | `str` | The use case to associate the event with. Events are namespaced by use case within a workspace.. | ✅ | | `external_id` | `str` | External identifier for correlation with other systems (max 1000 chars).. | ✅ | | `qc_result` | `str` | Quality check result: pass or fail.. | ✅ | | `location` | `str` | Location identifier for inventory count.. | ✅ | | `item_count` | `int` | Number of items counted.. | ✅ | | `item_type` | `str` | Type of item being counted.. | ✅ | | `alert_type` | `str` | Alert type identifier (e.g. no\_hardhat, spill\_detected).. | ✅ | | `severity` | `str` | Severity level for the safety alert.. | ✅ | | `alert_description` | `str` | Description of the safety alert.. | ✅ | | `custom_value` | `str` | Arbitrary value for custom events.. | ✅ | | `related_event_id` | `str` | The event ID of the event being reviewed.. | ✅ | | `feedback` | `str` | Operator feedback on the related event.. | ✅ | | `custom_metadata` | `Dict[str, Union[bool, float, int, str]]` | Flat key-value metadata to attach to the event. Keys must match pattern \[a-zA-Z0-9\_ -]+ (max 100 chars). String values max 1000 chars.. | ✅ | | `fire_and_forget` | `bool` | If True, the event is sent asynchronously and the workflow continues without waiting. If False, the block waits for the API response.. | ✅ | | `disable_sink` | `bool` | If True, the block is disabled and no events are sent.. | ✅ | | `cooldown_seconds` | `Union[float, int]` | Minimum number of seconds between consecutive events sent by this block. Events triggered during the cooldown period are dropped and the `throttling_status` output is set to True. Defaults to 1 second (at most 1 event per second) so high-frequency video workflows do not flood the Vision Events API with an event per frame. Set to 0 to disable rate limiting for intentionally bursty use cases.. | ✅ | | `write_to_event_store` | `bool` | If True, send the event to a local Event Ingestion Service (edge deployment) instead of the Roboflow Vision Events API (cloud). Images are embedded in the request and the event is posted to `/v2/events`. No Roboflow API key is required in this mode.. | ✅ | | `event_store_url` | `str` | Base URL of the local Event Ingestion Service. Only used when `Write to Local Event Store` is enabled.. | ✅ | The **Refs** column marks possibility to parametrise the property with dynamic values available in `workflow` runtime. See *Bindings* for more info. ### Runtime compatibility `soft` - runtime `hosted_serverless`, `dedicated_deployment`; execution `remote` : Cooldown / rate-limit timer is stored in process memory. With remote step execution on stateless or multi-replica HTTP runtimes each request gets a fresh worker, so cooldown does not throttle. Cooldown only behaves as documented with local step execution in a persistent WebRTC session. ### Input and Output Bindings The available connections depend on its binding kinds. Check what binding kinds `Roboflow Vision Events` in version `v1` has.
Input and output bindings * input * `input_image` ([*`image`*](/workflows/developer-guide/developer-guide/kinds/image.md)): The original input image. Uploaded to the Vision Events API and used as the base image for detection annotations.. * `output_image` ([*`image`*](/workflows/developer-guide/developer-guide/kinds/image.md)): An optional output/visualized image (e.g., from a visualization block). Displayed as the primary image in the Vision Events dashboard.. * `predictions` (*Union\[*[*`object_detection_prediction`*](/workflows/developer-guide/developer-guide/kinds/object-detection-prediction.md)*,* [*`classification_prediction`*](/workflows/developer-guide/developer-guide/kinds/classification-prediction.md)*,* [*`instance_segmentation_prediction`*](/workflows/developer-guide/developer-guide/kinds/instance-segmentation-prediction.md)*,* [*`keypoint_detection_prediction`*](/workflows/developer-guide/developer-guide/kinds/keypoint-detection-prediction.md)*]*): Optional model predictions to include as detection annotations on the input image. Supports object detection, instance segmentation, keypoint detection, and classification predictions.. * `event_type` ([*`string`*](/workflows/developer-guide/developer-guide/kinds/string.md)): The type of vision event to create.. * `solution` (*Union\[*[*`roboflow_solution`*](/workflows/developer-guide/developer-guide/kinds/roboflow-solution.md)*,* [*`string`*](/workflows/developer-guide/developer-guide/kinds/string.md)*]*): The use case to associate the event with. Events are namespaced by use case within a workspace.. * `external_id` ([*`string`*](/workflows/developer-guide/developer-guide/kinds/string.md)): External identifier for correlation with other systems (max 1000 chars).. * `qc_result` ([*`string`*](/workflows/developer-guide/developer-guide/kinds/string.md)): Quality check result: pass or fail.. * `location` ([*`string`*](/workflows/developer-guide/developer-guide/kinds/string.md)): Location identifier for inventory count.. * `item_count` ([*`integer`*](/workflows/developer-guide/developer-guide/kinds/integer.md)): Number of items counted.. * `item_type` ([*`string`*](/workflows/developer-guide/developer-guide/kinds/string.md)): Type of item being counted.. * `alert_type` ([*`string`*](/workflows/developer-guide/developer-guide/kinds/string.md)): Alert type identifier (e.g. no\_hardhat, spill\_detected).. * `severity` ([*`string`*](/workflows/developer-guide/developer-guide/kinds/string.md)): Severity level for the safety alert.. * `alert_description` ([*`string`*](/workflows/developer-guide/developer-guide/kinds/string.md)): Description of the safety alert.. * `custom_value` ([*`string`*](/workflows/developer-guide/developer-guide/kinds/string.md)): Arbitrary value for custom events.. * `related_event_id` ([*`string`*](/workflows/developer-guide/developer-guide/kinds/string.md)): The event ID of the event being reviewed.. * `feedback` ([*`string`*](/workflows/developer-guide/developer-guide/kinds/string.md)): Operator feedback on the related event.. * `custom_metadata` ([*`*`*](/workflows/developer-guide/developer-guide/kinds/wildcard.md)): Flat key-value metadata to attach to the event. Keys must match pattern \[a-zA-Z0-9\_ -]+ (max 100 chars). String values max 1000 chars.. * `fire_and_forget` ([*`boolean`*](/workflows/developer-guide/developer-guide/kinds/boolean.md)): If True, the event is sent asynchronously and the workflow continues without waiting. If False, the block waits for the API response.. * `disable_sink` ([*`boolean`*](/workflows/developer-guide/developer-guide/kinds/boolean.md)): If True, the block is disabled and no events are sent.. * `cooldown_seconds` (*Union\[*[*`float`*](/workflows/developer-guide/developer-guide/kinds/float.md)*,* [*`integer`*](/workflows/developer-guide/developer-guide/kinds/integer.md)*]*): Minimum number of seconds between consecutive events sent by this block. Events triggered during the cooldown period are dropped and the `throttling_status` output is set to True. Defaults to 1 second (at most 1 event per second) so high-frequency video workflows do not flood the Vision Events API with an event per frame. Set to 0 to disable rate limiting for intentionally bursty use cases.. * `write_to_event_store` ([*`boolean`*](/workflows/developer-guide/developer-guide/kinds/boolean.md)): If True, send the event to a local Event Ingestion Service (edge deployment) instead of the Roboflow Vision Events API (cloud). Images are embedded in the request and the event is posted to `/v2/events`. No Roboflow API key is required in this mode.. * `event_store_url` ([*`string`*](/workflows/developer-guide/developer-guide/kinds/string.md)): Base URL of the local Event Ingestion Service. Only used when `Write to Local Event Store` is enabled.. * output * `error_status` ([`boolean`](/workflows/developer-guide/developer-guide/kinds/boolean.md)): Boolean flag. * `throttling_status` ([`boolean`](/workflows/developer-guide/developer-guide/kinds/boolean.md)): Boolean flag. * `event_id` ([`string`](/workflows/developer-guide/developer-guide/kinds/string.md)): String value. * `message` ([`string`](/workflows/developer-guide/developer-guide/kinds/string.md)): String value.
Example JSON definition ```json { "name": "", "type": "roboflow_core/roboflow_vision_events@v1", "input_image": "$inputs.image", "output_image": "$steps.visualization.image", "predictions": "$steps.object_detection_model.predictions", "event_type": "quality_check", "solution": "my-use-case", "external_id": "batch-2025-001", "qc_result": "pass", "location": "warehouse-A", "item_count": 42, "item_type": "widget", "alert_type": "no_hardhat", "severity": "high", "alert_description": "Worker detected without hardhat in zone B", "custom_value": "anomaly detected at 14:32", "related_event_id": "evt_abc123", "feedback": "correct", "custom_metadata": { "camera_id": "cam_01", "location": "$inputs.location" }, "fire_and_forget": true, "disable_sink": false, "cooldown_seconds": 1, "write_to_event_store": false, "event_store_url": "http://localhost:8001" } ```