Write Vision Event Bundle

Write vision events as self-contained tarball bundles to a local directory.

Serialize vision events as self-contained tarball bundles on the local filesystem instead of sending them to the Roboflow Vision Events API. Designed for air-gapped and OT-network deployments where the inference server has no route to the cloud: a customer file-mover service transports the bundles out of the network, and an uploader later POSTs each bundle to Roboflow's POST /vision-events/bundle endpoint without unpacking it.

Bundle Format (version 1)

One tarball per event, written to target_directory:

event_<UTC timestamp>_<eventId>.tar.gz
├── payload.json               # the event payload (versioned contract, camelCase)
└── images/<file_id>.jpg       # image members, file_id is a uuid4

payload.json has the same shape as the POST /vision-events request body, with these differences:

• bundleFormatVersion identifies the bundle contract version (currently 1)

• images[].file / images[].inputFile reference tar member paths instead of sourceId / inputSourceId (the cloud resolves them to source ids at ingest time)

• useCaseId is only present when the optional Use Case field is set on this block; air-gapped deployments typically leave it unset so no cloud identifiers are stored in the OT network, and the uploader supplies it via the useCaseId query parameter instead

Media members live under type-named directories (images/ today); future media types will use sibling directories, so consumers should ignore unknown top-level directories.

Atomic Writes

Bundles are written to a dot-prefixed temporary file in the target directory, fsynced, and atomically renamed to their final event_*.tar.gz name (the directory is fsynced after the rename). A file-mover service that matches event_*.tar.gz (or skips dotfiles) can never pick up a partially written bundle.

Rate Limiting

Video workflows can run many times per second, which by default would write a bundle for every frame. The block enforces a cooldown between consecutive events: at most one event per second is written 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.

Requirements

Local Filesystem Access: This block requires write access to the local filesystem and is intended for self-hosted inference. Filesystem access can be controlled via environment variables:

• Set ALLOW_WORKFLOW_BLOCKS_ACCESSING_LOCAL_STORAGE=False to disable the block (it will raise an error)

• Set WORKFLOW_BLOCKS_WRITE_DIRECTORY to an absolute path to restrict writes to a specific directory and its subdirectories only

No Roboflow API key is required: the block never talks to the network.

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)

Type identifier

Use the following identifier in step "type" field: roboflow_core/vision_event_bundle@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..	❌
target_directory	str	Directory path where event bundles will be written. Created automatically if it does not exist. If WORKFLOW_BLOCKS_WRITE_DIRECTORY is set, this path must be a subdirectory of the allowed directory..	✅
event_type	str	The type of vision event to create..	✅
solution	str	Optional use case to bake into the bundle as useCaseId. Leave unset in air-gapped deployments so no cloud identifiers are stored in the bundle - the uploader supplies the use case at upload time instead. A useCaseId query parameter passed to the ingest endpoint always overrides the bundled value..	✅
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 bundle is written asynchronously and the workflow continues without waiting. If False, the block waits for the write to finish..	✅
disable_sink	bool	If True, the block is disabled and no bundles are written..	✅
cooldown_seconds	Union[float, int]	Minimum number of seconds between consecutive event bundles written by this block. Events triggered during the cooldown period are dropped and the throttling_status output is set to True. Defaults to 1 second so high-frequency video workflows do not write a bundle per frame. Set to 0 to disable rate limiting for intentionally bursty use cases..	✅

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 inside an InferencePipeline.

soft - runtime dedicated_deployment : Bundles are persisted on the deployment's volume but are not retrievable through the Roboflow API; this block is intended for self-hosted deployments with a file-mover process.

soft - runtime hosted_serverless : Container disk is ephemeral, so bundles are lost when the worker scales down; if there's more than one replica consuming workflow requests the result will be non deterministic.

Input and Output Bindings

The available connections depend on its binding kinds. Check what binding kinds Write Vision Event Bundle in version v1 has.

Input and output bindings

• input

  • target_directory (string): Directory path where event bundles will be written. Created automatically if it does not exist. If WORKFLOW_BLOCKS_WRITE_DIRECTORY is set, this path must be a subdirectory of the allowed directory..

  • input_image (image): The original input image. Stored in the bundle and used as the base image for detection annotations..

  • output_image (image): An optional output/visualized image (e.g., from a visualization block). Displayed as the primary image once the event is ingested..

  • predictions (Union[classification_prediction, instance_segmentation_prediction, keypoint_detection_prediction, object_detection_prediction]): 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): The type of vision event to create..

  • solution (Union[roboflow_solution, string]): Optional use case to bake into the bundle as useCaseId. Leave unset in air-gapped deployments so no cloud identifiers are stored in the bundle - the uploader supplies the use case at upload time instead. A useCaseId query parameter passed to the ingest endpoint always overrides the bundled value..

  • external_id (string): External identifier for correlation with other systems (max 1000 chars)..

  • qc_result (string): Quality check result: pass or fail..

  • location (string): Location identifier for inventory count..

  • item_count (integer): Number of items counted..

  • item_type (string): Type of item being counted..

  • alert_type (string): Alert type identifier (e.g. no_hardhat, spill_detected)..

  • severity (string): Severity level for the safety alert..

  • alert_description (string): Description of the safety alert..

  • custom_value (string): Arbitrary value for custom events..

  • related_event_id (string): The event ID of the event being reviewed..

  • feedback (string): Operator feedback on the related event..

  • custom_metadata (*): 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): If True, the bundle is written asynchronously and the workflow continues without waiting. If False, the block waits for the write to finish..

  • disable_sink (boolean): If True, the block is disabled and no bundles are written..

  • cooldown_seconds (Union[float, integer]): Minimum number of seconds between consecutive event bundles written by this block. Events triggered during the cooldown period are dropped and the throttling_status output is set to True. Defaults to 1 second so high-frequency video workflows do not write a bundle per frame. Set to 0 to disable rate limiting for intentionally bursty use cases..

• output

  • error_status (boolean): Boolean flag.

  • throttling_status (boolean): Boolean flag.

  • event_id (string): String value.

  • bundle_path (string): String value.

  • message (string): String value.

Example JSON definition

{
	    "name": "<your_step_name_here>",
	    "type": "roboflow_core/vision_event_bundle@v1",
	    "target_directory": "/data/vision-event-bundles",
	    "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
	}