Vision Events

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:

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

MCP Server

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