> 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/deployment/monitoring-and-analytics/vision-events.md). # 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](https://docs.roboflow.com/deployment/monitoring-and-analytics/vision-events#http-api). {% embed url="" %} ### 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](/deployment/monitoring-and-analytics/vision-events/send-events.md) - send events from a Workflow block, the REST API, or edge device backup. * [Add Images for Training](/deployment/monitoring-and-analytics/vision-events/add-images-for-training.md) - move captured event images into a project to train a model. * [Operator Feedback](/deployment/monitoring-and-analytics/vision-events/operator-feedback.md) - let team members mark events correct, incorrect, or inconclusive. * [Delete Events](/deployment/monitoring-and-analytics/vision-events/delete-events.md) - 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](/deployment/monitoring-and-analytics/vision-events/upload-a-vision-event-image.md#http-api) * [Create a Vision Event](/deployment/monitoring-and-analytics/vision-events/create-a-vision-event.md#http-api) * [Batch Create Vision Events](/deployment/monitoring-and-analytics/vision-events/batch-create-vision-events.md#http-api) * [Query Vision Events](/deployment/monitoring-and-analytics/vision-events/query-events.md#http-api) * [List Use Cases](/deployment/monitoring-and-analytics/vision-events/use-cases.md#http-api) * [Get Custom Metadata Schema](/deployment/monitoring-and-analytics/vision-events/get-custom-metadata-schema.md#http-api) ### 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](https://docs.roboflow.com/reference/authentication/authentication/scoped-api-keys) 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](https://docs.roboflow.com/deployment/monitoring-and-analytics/vision-events/use-cases). You can also [list existing use cases](/deployment/monitoring-and-analytics/vision-events/use-cases.md#http-api) 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](#http-api). ### Quick Start ```python 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()`](/deployment/monitoring-and-analytics/vision-events/upload-a-vision-event-image.md#python-sdk) | Upload an image for use in events | | [`write_vision_event()`](/deployment/monitoring-and-analytics/vision-events/create-a-vision-event.md#python-sdk) | Create a single vision event | | [`write_vision_events_batch()`](/deployment/monitoring-and-analytics/vision-events/batch-create-vision-events.md#python-sdk) | Create up to 100 events in one request | | [`query_vision_events()`](/deployment/monitoring-and-analytics/vision-events/query-events.md#python-sdk) | Query events with filters and pagination | | [`query_all_vision_events()`](/deployment/monitoring-and-analytics/vision-events/query-events.md#paginate-through-all-results) | Auto-paginating query across all matching events | | [`list_vision_event_use_cases()`](/deployment/monitoring-and-analytics/vision-events/use-cases.md#python-sdk) | List use cases in your workspace | | [`create_vision_event_use_case()`](/deployment/monitoring-and-analytics/vision-events/use-cases.md#create-a-use-case) | Create a new use case | | [`rename_vision_event_use_case()`](/deployment/monitoring-and-analytics/vision-events/use-cases.md#rename-a-use-case) | Rename a use case | | [`archive_vision_event_use_case()`](/deployment/monitoring-and-analytics/vision-events/use-cases.md#archive-a-use-case) | Archive a use case | | [`unarchive_vision_event_use_case()`](/deployment/monitoring-and-analytics/vision-events/use-cases.md#unarchive-a-use-case) | Unarchive a use case | | [`get_vision_event_metadata_schema()`](/deployment/monitoring-and-analytics/vision-events/get-custom-metadata-schema.md#python-sdk) | Get discovered custom metadata field types |