> 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/query-events.md). # Query Events Search, filter, and browse Vision Events in the dashboard, ask the Agent in natural language, or query via the API ## About This page covers how to find specific [Vision Events](/deployment/monitoring-and-analytics/vision-events.md) (the timestamped records of what your deployed models observed) by filtering and searching them in the Vision Events dashboard or through the REST API. Narrow results by date range, event type, device, stream, workflow, detected class, or feedback status to audit production behavior and build reports. You can also ask the [Roboflow Agent](https://docs.roboflow.com/agents/roboflow-agent) questions about your events in natural language. ### Saved Filters A saved filter belongs to its Use Case, so everyone in the Workspace can open it. Relative dates stay relative: a saved filter for the last 7 days always shows the most recent 7 days. Anyone who can create Vision Events can save over a filter. Only the person who saved it, or someone who can manage Vision Events, can rename or delete it. ### Auto-Finalized Events An auto-finalized event was closed automatically on the edge device before its video finished uploading, so the video is missing. The event still has its result and still images. This applies only to events synced through [Edge Device Backup](/deployment/monitoring-and-analytics/vision-events/send-events.md#edge-device-backup). ### Agent Queries Asking the Agent about events requires the "View Vision Events" [permission](https://docs.roboflow.com/platform/enterprise-features/role-based-access-control). If a question reaches past your Workspace's [retention window](/deployment/monitoring-and-analytics/vision-events.md#data-retention), the Agent tells you the earliest date it can query instead of answering zero. Date boundaries and time buckets use UTC. ## Web App ### Filter Events Open "Vision Events" and click a Use Case to see its events, newest first.
Use the filter bar to narrow results by date, event ID, event type, device, stream, Workflow, detection (with an optional confidence threshold), feedback, custom metadata, video count, or ingestion warnings. A start or end date can be "Relative" (ex: 7 days ago) or "Absolute" (a fixed date and time). Text filters (ex: device, stream, custom metadata) can also match part of a value with "Contains", "Starts With", or "Ends With". These matches are case-sensitive. Most filters can also check whether a field "Is Set". Use the "is / is not" toggle to match the opposite. To find events that match one set of filters or another, click "OR" to add a row of filters. An event shows when it matches every filter in at least one row. The dates apply to all rows. Click a value in the event detail sidebar (ex: a device ID or custom metadata value) to add it as a filter. Click an active filter chip to change its value or operator. The total count of matching events appears above the results, even while the list is still loading. If the Use Case has [event values](/deployment/monitoring-and-analytics/vision-events/use-cases.md#event-value), the total value of the matching events appears too. To reuse filters, open "Saved Filters" at the start of the filter bar and click "Save Current Filters". Use "Copy Link" to share one. See [Saved Filters](#saved-filters) for who can change them. To keep an event, open it and click the star in the header, or press `S`. Your stars are private to you and to the Use Case. To see them, open the "Lists" menu next to "Saved Filters" and pick "Starred". A starred event stays visible after it passes the [retention window](/deployment/monitoring-and-analytics/vision-events.md#data-retention). You can star up to 1,000 events per Use Case. To make your own list, open "Lists" and create one, either private or shared with the Workspace. Add an event to it with the list button next to the star. Anyone who can create Vision Events can add events to a shared list, but only its creator or someone who can manage Vision Events can rename or delete it.
### View Event Details Click an event to see its images, video clips, source metadata, predictions, event data, custom metadata, and [value](/deployment/monitoring-and-analytics/vision-events/use-cases.md#event-value). If the event has detections, segmentations, or keypoints, check "Draw Detections" to draw them on the source image. This helps when your pipeline saves only the input image. Your browser remembers this choice for all events and the fullscreen view. The checkbox is hidden on output images, which already show detections. A play icon on an event card means it has [video clips](/deployment/monitoring-and-analytics/vision-events/upload-a-vision-event-video.md). Clips play in the "Media" strip after the images, and a clip that is still processing plays once it is ready. Detection overlays and fullscreen work on images only, and you cannot [add clips for training](/deployment/monitoring-and-analytics/vision-events/add-images-for-training.md). A crossed-out video icon marks an [auto-finalized event](#auto-finalized-events). Its detail view shows when it was finalized. ### Ask the Agent Click "Agent" in the left sidebar and ask the [Roboflow Agent](https://docs.roboflow.com/agents/roboflow-agent) about a Use Case (ex: "How many failures did assembly-line-qa have last week?"). It answers by querying your event data. It can count events, track pass and fail rates over time, compute sums, averages, minimums, maximums, and unique counts of numeric fields, group totals by field, custom metadata, day, or week, and list the events themselves (ex: "Show me the events from device X"). Ask for more to see the next page of events. "Analyze with AI" on a Use Case's Overview or Search tab opens the Agent in a new tab with a question ready to send. From the Search tab, the question includes your current filters. For a recurring emailed digest, see [Summary Reports](/deployment/monitoring-and-analytics/vision-events/summary-reports.md). ## HTTP API ### Query Vision Events Query vision events with filters, time ranges, and pagination. This endpoint supports filtering by event type, device context, detection classes, custom metadata, image metadata, and event-specific fields. **Required scope:** `vision-events:read` or `device:read` {% openapi src="/files/sCDP9kVopV4JkkRK7GDd" path="/vision-events/query" method="post" %} [openapi.yaml](https://1583372177-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoksNmwps1HmYr8TqHDnX%2Fuploads%2Fgit-blob-a9a047ab072c81c5d90fa9f286b19944c4fde777%2Fopenapi.yaml?alt=media) {% endopenapi %} {% hint style="info" %} The `detection` filter was previously named `detectionClass`. The old name is no longer accepted. {% endhint %} Each video in the results lists only its `sourceId` and `label`. To play or download one, [get a playback URL](/deployment/monitoring-and-analytics/vision-events/upload-a-vision-event-video.md#get-a-playback-url) for its `sourceId`. To match one set of filters or another, send them as a `filterGroup`. To run a saved filter, send its ID as `savedFilterId`. You get the same events the Search tab shows for that filter. ### Saved Filters Saved filters are the same ones the Search tab shows, so a filter you save through the API appears in the web app. A raw API key acts for the workspace and owns no filter. To rename or delete any filter, it needs the `vision-events:manage` scope. An OAuth token acts as its user, so that user can rename and delete their own filters with `vision-events:write`. Changes to someone else's filter are written to the workspace audit log. {% openapi src="/files/sCDP9kVopV4JkkRK7GDd" path="/vision-events/use-cases/{useCaseId}/saved-filters" method="get" %} [openapi.yaml](https://1583372177-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoksNmwps1HmYr8TqHDnX%2Fuploads%2Fgit-blob-a9a047ab072c81c5d90fa9f286b19944c4fde777%2Fopenapi.yaml?alt=media) {% endopenapi %} {% openapi src="/files/sCDP9kVopV4JkkRK7GDd" path="/vision-events/use-cases/{useCaseId}/saved-filters/{savedFilterId}" method="get" %} [openapi.yaml](https://1583372177-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoksNmwps1HmYr8TqHDnX%2Fuploads%2Fgit-blob-a9a047ab072c81c5d90fa9f286b19944c4fde777%2Fopenapi.yaml?alt=media) {% endopenapi %} {% openapi src="/files/sCDP9kVopV4JkkRK7GDd" path="/vision-events/use-cases/{useCaseId}/saved-filters" method="post" %} [openapi.yaml](https://1583372177-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoksNmwps1HmYr8TqHDnX%2Fuploads%2Fgit-blob-a9a047ab072c81c5d90fa9f286b19944c4fde777%2Fopenapi.yaml?alt=media) {% endopenapi %} {% openapi src="/files/sCDP9kVopV4JkkRK7GDd" path="/vision-events/use-cases/{useCaseId}/saved-filters/{savedFilterId}" method="patch" %} [openapi.yaml](https://1583372177-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoksNmwps1HmYr8TqHDnX%2Fuploads%2Fgit-blob-a9a047ab072c81c5d90fa9f286b19944c4fde777%2Fopenapi.yaml?alt=media) {% endopenapi %} {% openapi src="/files/sCDP9kVopV4JkkRK7GDd" path="/vision-events/use-cases/{useCaseId}/saved-filters/{savedFilterId}" method="delete" %} [openapi.yaml](https://1583372177-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoksNmwps1HmYr8TqHDnX%2Fuploads%2Fgit-blob-a9a047ab072c81c5d90fa9f286b19944c4fde777%2Fopenapi.yaml?alt=media) {% endopenapi %} ## Python SDK Query vision events with filters, time ranges, and pagination. ### Single Page Query Use `query_vision_events()` to fetch a single page of results: ```python import roboflow roboflow.login() rf = roboflow.Roboflow() ws = rf.workspace() page = ws.query_vision_events( "a1b3c8e1", # use case ID (required) event_type="quality_check", # filter by single event type start_time="2024-01-14T00:00:00Z", # ISO 8601 start time end_time="2024-01-15T23:59:59Z", # ISO 8601 end time limit=50, # max events per page ) for evt in page["events"]: print(evt["eventId"], evt["eventData"]) ``` You can also pass additional filters as keyword arguments. These are forwarded directly to the API: ```python page = ws.query_vision_events( "a1b3c8e1", event_types=["quality_check", "safety_alert"], deviceId={"operator": "eq", "value": "camera-node-5"}, customMetadataFilters=[ {"field": "temperature", "operator": "gt", "value": 70, "type": "number"} ], eventFieldFilters=[ {"column": "result", "operator": "eq", "value": "fail"} ], ) ``` For manual pagination, use the `cursor` parameter with the `nextCursor` value from a previous response: ```python all_events = [] page = ws.query_vision_events("a1b3c8e1", limit=100) all_events.extend(page.get("events", [])) while page.get("hasMore"): page = ws.query_vision_events("a1b3c8e1", cursor=page["nextCursor"], limit=100) all_events.extend(page.get("events", [])) ``` ### Paginate Through All Results Use `query_all_vision_events()` to automatically paginate through all matching events. It yields one page of events at a time: ```python all_events = [] for page in ws.query_all_vision_events( "a1b3c8e1", event_type="quality_check", start_time="2024-01-14T00:00:00Z", end_time="2024-01-15T23:59:59Z", ): all_events.extend(page) print(f"Found {len(all_events)} events") ``` For full details on available filters, operators, and response formats, see the [REST API reference](#http-api). ## MCP Server Connect your AI agent to the [MCP Server](https://docs.roboflow.com/agents/mcp-server) and it can answer questions about your events with these tools:
ToolDescription
vision_events_queryQuery production vision events with filters and pagination.
vision_events_use_cases_listList the vision event use cases in the workspace.
vision_events_custom_metadata_schema_getGet the custom metadata schema discovered for a use case.