Vision Events

Record, search, and analyze what your deployed computer vision models see in production.

About

Overview

Vision Events is a Roboflow datastore that can capture important events, like the detection of defect or a count of inventory, alongside visual information from your deployed computer vision model. This gives you a searchable, filterable history of everything your vision system observes in production.

What is a Vision Event?

A Vision Event is a timestamped record created when a model processes an image. Each event can optionally capture:

• Images: The original images that were processed and associated output images

• Predictions: Object detections, classifications, instance segmentations, or keypoints returned by the model

• Source metadata: Which device, stream, or workflow generated the event

• Custom metadata: Key-value pairs you define for your domain (e.g. line_number, shift, part_number)

For programmatic access, see the Vision Events API Reference.

Key Concepts

Use Cases

A Use Case groups events that share a common purpose and custom metadata structure. Events in the same Use Case typically send similar metadata fields so you can filter and query them consistently.

For example, a "Defect Detection" Use Case might always include line_id, shift, and part_number even if events come from multiple factories or camera locations. Create separate Use Cases when the metadata structure is fundamentally different (e.g. "PPE Compliance" tracks zone and alert_type instead).

In this section

• Send Events - send events from a Workflow block, the REST API, or edge device backup.

• Query Events - filter events in the dashboard, ask the Agent in natural language, or query via the API.

• Add Images for Training - move captured event images into a project to train a model.

• Operator Feedback - let team members mark events correct, incorrect, or inconclusive.

• Summary Reports - email your team a recurring digest of a Use Case.

• Delete Events - remove events you no longer need from a Use Case.

HTTP API

The Vision Events API lets you record structured events from your computer vision deployments, then query and analyze them. Events can include images, detection annotations, custom metadata, and type-specific data for quality checks, inventory counts, safety alerts, and more.

With the Vision Events API, you can:

• Upload a Vision Event Image

• Create a Vision Event

• Batch Create Vision Events

• Upload a Vision Event Bundle

• Query Vision Events

• List Use Cases

• Get Custom Metadata Schema

Authentication

All Vision Events endpoints use Bearer token authentication with your Roboflow API key:

Authorization: Bearer YOUR_API_KEY

Vision Events endpoints require specific scoped API key permissions:

• Read operations (query, list, schema): vision-events:read or device:read

• Write operations (create, batch, upload): vision-events:write or device:update

Use Cases

Each vision event is associated with a use case. To learn how to create and manage use cases, see the Use Cases documentation.

You can also list existing use cases that have recorded events via the API.

Event Types

The API supports five event types, each with its own eventData schema:

Event Type	Description
quality_check	QA and inspection results
inventory_count	Inventory measurements
safety_alert	Safety incidents and alerts
custom	Freeform event data
operator_feedback	Human feedback on model predictions

Data Retention

Events are retained for a configurable lookback window (default: 14 days). The lookbackDays value is returned in query responses so you know the effective retention period for your workspace.

Python SDK

The Roboflow Python SDK provides methods for working with vision events on the Workspace object. You can create events, query them with filters and pagination, upload images, and manage use cases.

For full details on event schemas, filtering options, and response formats, see the Vision Events REST API documentation.

Quick Start

import roboflow

roboflow.login()

rf = roboflow.Roboflow()
ws = rf.workspace()

# Create a use case
result = ws.create_vision_event_use_case("manufacturing-qa")
use_case_id = result["id"]

# Upload an image
img = ws.upload_vision_event_image("photo.jpg")

# Create an event with the uploaded image
ws.write_vision_event({
    "eventId": "c3d4e5f6-a1b2-4c3d-8e5f-6a7b8c9d0e1f",
    "eventType": "quality_check",
    "useCaseId": use_case_id,
    "timestamp": "2024-01-15T10:30:00Z",
    "images": [{"sourceId": img["sourceId"]}],
    "eventData": {"result": "pass"},
})

# Query events
for page in ws.query_all_vision_events(use_case_id):
    for evt in page:
        print(evt["eventId"], evt["eventType"])

Available Methods

Method	Description
upload_vision_event_image()	Upload an image for use in events
write_vision_event()	Create a single vision event
write_vision_events_batch()	Create up to 100 events in one request
query_vision_events()	Query events with filters and pagination
query_all_vision_events()	Auto-paginating query across all matching events
list_vision_event_use_cases()	List use cases in your workspace
create_vision_event_use_case()	Create a new use case
rename_vision_event_use_case()	Rename a use case
archive_vision_event_use_case()	Archive a use case
unarchive_vision_event_use_case()	Unarchive a use case
get_vision_event_metadata_schema()	Get discovered custom metadata field types

MCP Server

Connect your AI agent to the MCP Server and it can look at production events with these tools:

Tool	Description
vision_events_query	Query production vision events for a use case.
vision_events_use_cases_list	List the vision event use cases in the workspace.
vision_events_use_case_create	Create a new vision event use case.
vision_events_custom_metadata_schema_get	Get the custom metadata schema discovered for a use case.