이벤트 쿼리
대시보드에서 Vision Event를 검색, 필터링, 탐색하거나, Agent에게 자연어로 질문하거나, API로 쿼리합니다
소개
이 페이지에서는 특정 항목을 찾는 방법을 다룹니다 Vision Events (배포된 모델이 관찰한 내용의 타임스탬프가 있는 기록) 을 Vision Events 대시보드 또는 REST API에서 필터링하고 검색하여 확인할 수 있습니다. 날짜 범위, 이벤트 유형, 디바이스, 스트림, 워크플로, 감지된 클래스 또는 피드백 상태로 결과를 좁혀 운영 동작을 감사하고 보고서를 작성할 수 있습니다. 또한 Roboflow Agent 자연어로 이벤트에 대해 질문할 수 있습니다.
저장된 필터
저장된 필터는 해당 사용 사례에 속하므로 워크스페이스의 모든 사람이 열 수 있습니다. 상대 날짜는 상대적인 상태로 유지됩니다. 예를 들어, 최근 7일에 대한 저장된 필터는 항상 가장 최근 7일을 표시합니다. Vision Events를 만들 수 있는 사람은 누구나 필터를 덮어써서 저장할 수 있습니다. 저장한 사람이나 Vision Events를 관리할 수 있는 사람만 이름을 바꾸거나 삭제할 수 있습니다.
자동 최종화된 이벤트
자동 최종화된 이벤트는 동영상 업로드가 완료되기 전에 엣지 디바이스에서 자동으로 종료되었기 때문에 동영상이 없습니다. 이벤트에는 여전히 결과와 정지 이미지가 있습니다. 이 내용은 다음을 통해 동기화된 이벤트에만 적용됩니다 엣지 디바이스 백업.
에이전트 쿼리
에이전트에게 이벤트에 대해 질문하려면 "Vision Events 보기" 권한. 질문이 워크스페이스의 보존 기간을 넘으면, 에이전트는 0을 답하는 대신 쿼리할 수 있는 가장 이른 날짜를 알려줍니다. 날짜 경계와 시간 버킷은 UTC를 사용합니다.
웹 앱
이벤트 필터링
"Vision Events"를 열고 사용 사례를 클릭하여 최신 항목부터 이벤트를 확인하세요.

필터 바를 사용해 날짜, 이벤트 유형, 디바이스, 스트림, 워크플로, 감지(선택적 신뢰도 임계값 포함), 피드백, 사용자 지정 메타데이터, 동영상 수 또는 수집 경고로 결과를 좁힙니다. 시작 날짜 또는 종료 날짜는 "상대적"(예: 7일 전) 또는 "절대적"(고정된 날짜 및 시간)일 수 있습니다.
이벤트 세부 정보 사이드바에서 값(예: 디바이스 ID 또는 사용자 지정 메타데이터 값)을 클릭해 필터로 추가하세요. 활성 필터 칩을 클릭해 값이나 연산자를 변경할 수 있습니다.
일치하는 이벤트의 총 개수는 목록이 아직 로드 중일 때도 결과 위에 표시됩니다. 사용 사례에 이벤트 값이 있으면 일치하는 이벤트의 총값도 표시됩니다.
필터를 재사용하려면 필터 바 시작 부분에서 "저장된 필터"를 열고 "현재 필터 저장"을 클릭하세요. 하나를 공유하려면 "링크 복사"를 사용하세요. 참조 저장된 필터 누가 변경할 수 있는지.
이벤트를 보관하려면 이벤트를 열고 헤더의 별표를 클릭하거나 S를 누르세요. 별표 표시한 항목은 본인에게만 그리고 사용 사례에만 비공개입니다. 보려면 "저장된 필터" 옆의 "목록" 메뉴를 열고 "별표 표시됨"을 선택하세요. 별표 표시한 이벤트는 보존 기간보존 기간

이벤트 세부 정보 보기
이벤트를 클릭하면 이미지, 비디오 클립, 소스 메타데이터, 예측, 이벤트 데이터, 사용자 지정 메타데이터 및 값.
이벤트에 감지, 세그멘테이션 또는 키포인트가 있으면 "감지 그리기"를 체크하여 소스 이미지 위에 그리세요. 이는 파이프라인이 입력 이미지만 저장할 때 유용합니다. 브라우저는 이 선택을 모든 이벤트와 전체 화면 보기에서 기억합니다. 이 체크박스는 이미 감지를 표시하는 출력 이미지에서는 숨겨져 있습니다.
이벤트 카드의 재생 아이콘은 해당 이벤트에 비디오 클립이 있음을 의미합니다. 클립은 이미지 뒤의 "미디어" 스트립에서 재생되며, 아직 처리 중인 클립은 준비되면 재생됩니다. 감지 오버레이와 전체 화면은 이미지에서만 작동하며, 클립을 훈련용으로 추가할 수는 없습니다.
취소선이 그어진 비디오 아이콘은 자동 최종화된 이벤트를 표시합니다. 세부 보기에는 최종화된 시점이 표시됩니다.
에이전트에게 질문하기
왼쪽 사이드바에서 "Agent"를 클릭하고 Roboflow Agent 사용 사례에 대해 질문하세요(예: "지난주 assembly-line-qa의 실패는 몇 건이었나요?"). 이벤트 데이터를 쿼리하여 답변합니다. 이벤트 수를 세고, 시간 경과에 따른 성공 및 실패율을 추적하고, 수치 필드의 합계, 평균, 최소값, 최대값 및 고유 개수를 계산하고, 필드, 사용자 지정 메타데이터, 일 또는 주별로 총계를 그룹화하며, 이벤트 자체를 나열할 수 있습니다(예: "디바이스 X의 이벤트를 보여 주세요"). 다음 페이지의 이벤트를 보려면 더 많이 요청하세요.
사용 사례의 개요 또는 검색 탭에서 "AI로 분석"을 클릭하면 보낼 질문이 준비된 새 탭에서 에이전트가 열립니다. 검색 탭에서는 질문에 현재 필터가 포함됩니다.
반복되는 이메일 요약은 요약 보고서.
HTTP API
Vision Events 쿼리
필터, 시간 범위, 페이지네이션을 사용해 비전 이벤트를 조회합니다. 이 엔드포인트는 이벤트 유형, 디바이스 컨텍스트, 탐지 클래스, 사용자 정의 메타데이터, 이미지 메타데이터, 이벤트별 필드를 기준으로 필터링을 지원합니다.
필수 범위: vision-events:read 또는 device:read
Query vision events with filters, time ranges, and pagination. Events come newest first and only from the workspace's retention window. Requires the vision-events:read or device:read scope. imageMetadataFilters and savedFilterId need vision-events:read.
Roboflow API key passed as a Bearer token.
The use case ID to query events for.
Start of the time range.
End of the time range.
Filter to one event type. To filter to several, use eventTypes.
Filter to events that have (true) or do not have (false) ingestion warnings.
The nextCursor from a previous response, to fetch the next page.
Number of events to return per page.
100Start the first page at this event, so it is the first result. Ignored when you send cursor. The response sets anchorFound.
Run a saved filter of this use case instead of sending filters. Send only useCaseId, limit, and cursor with it. Requires the vision-events:read scope and does not work with device API keys. Relative dates resolve on the first page and stay fixed for later pages. Sending any other filter with it returns 400.
Yq3mT8vR2nKpQuery results.
True when more events match. Pass nextCursor as cursor to get the next page.
Cursor for the next page. null when hasMore is false.
Returned when you sent anchorEventId. False when that event is not in the retention window.
The workspace's retention window in days (14 by default).
Deprecated field names used in the request.
Invalid query.
Insufficient permissions for this resource.
The savedFilterId does not exist in this use case, or the use case does not exist or is archived.
The saved filter can no longer be read. Save it again from the Search tab.
POST /vision-events/query HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 242
{
"useCaseId": "a1b3c8e1",
"startTime": "2024-01-14T00:00:00Z",
"endTime": "2024-01-15T23:59:59Z",
"eventTypes": [
"quality_check",
"safety_alert"
],
"customMetadataFilters": [
{
"field": "temperature",
"operator": "gt",
"value": 70,
"type": "number"
}
],
"limit": 50
}{
"events": [
{
"eventId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"eventType": "quality_check",
"timestamp": "2024-01-15T10:30:00.000Z",
"images": [
{
"label": "inspection-photo",
"objectDetections": [
{
"class": "defect",
"x": 100,
"y": 200,
"width": 50,
"height": 30,
"confidence": 0.95
}
]
}
],
"videos": [
{
"sourceId": "Kq4vX8mNp2RtY6wZ1bCd",
"label": "line-3 camera"
}
],
"eventData": {
"result": "fail",
"externalId": "batch-001"
},
"customMetadata": {
"line": "A1",
"temperature": 72.5
}
}
],
"hasMore": true,
"nextCursor": "eyJ0aW1lc3RhbXAiOiIyMDI0LTAxLTE1IiwiZXZlbnRJZCI6InFjLTAwMSJ9",
"lookbackDays": 14
}결과의 각 비디오는 다음만 표시합니다 sourceId 그리고 label. 재생하거나 다운로드하려면, 재생 URL을 가져오세요 해당 sourceId.
저장된 필터를 실행하려면, 해당 ID를 다음으로 보내세요: savedFilterId. 해당 필터에 대해 검색 탭에 표시되는 것과 동일한 이벤트를 받게 됩니다.
저장된 필터
저장된 필터는 검색 탭에 표시되는 것과 동일하므로, API를 통해 저장한 필터는 웹 앱에 나타납니다. 원시 API 키는 워크스페이스에 대해 동작하며 어떤 필터도 소유하지 않습니다. 필터의 이름을 바꾸거나 삭제하려면 다음이 필요합니다: vision-events:manage 범위. OAuth 토큰은 해당 사용자로 작동하므로, 그 사용자는 다음을 사용해 자신의 필터 이름을 바꾸고 삭제할 수 있습니다: vision-events:write. 다른 사람의 필터에 대한 변경 사항은 워크스페이스 감사 로그에 기록됩니다.
List the saved filters of a use case, sorted by name. Requires the vision-events:read scope and the View Vision Events permission.
Roboflow API key passed as a Bearer token.
The use case the filters belong to.
The use case's saved filters.
Insufficient permissions, or a device API key.
The use case does not exist or is archived.
GET /vision-events/use-cases/{useCaseId}/saved-filters HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"savedFilters": [
{
"id": "Yq3mT8vR2nKp",
"name": "Line 3 misses",
"filters": [
{
"category": "startDate",
"operator": "gte",
"value": "now-7d",
"label": "Start Date: 7 days ago"
},
{
"category": "customMetadata",
"field": "line_id",
"type": "string",
"operator": "eq",
"value": "3",
"label": "line_id: 3"
}
],
"createdBy": "text",
"createdAt": "2026-01-01T00:00:00.000Z",
"updatedBy": "text",
"updatedAt": "2026-01-01T00:00:00.000Z"
}
]
}Get one saved filter. Requires the vision-events:read scope and the View Vision Events permission.
Roboflow API key passed as a Bearer token.
The use case the filter belongs to.
The saved filter ID.
The saved filter.
Insufficient permissions, or a device API key.
The saved filter or its use case does not exist, or the use case is archived.
The saved filter can no longer be read. Save it again from the Search tab.
GET /vision-events/use-cases/{useCaseId}/saved-filters/{savedFilterId} HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"savedFilter": {
"id": "Yq3mT8vR2nKp",
"name": "Line 3 misses",
"filters": [
{
"category": "startDate",
"operator": "gte",
"value": "now-7d",
"label": "Start Date: 7 days ago"
},
{
"category": "customMetadata",
"field": "line_id",
"type": "string",
"operator": "eq",
"value": "3",
"label": "line_id: 3"
}
],
"createdBy": "text",
"createdAt": "2026-01-01T00:00:00.000Z",
"updatedBy": "text",
"updatedAt": "2026-01-01T00:00:00.000Z"
}
}Save a set of filters to a use case. Every member of the workspace who can view Vision Events can open it. Requires the vision-events:write scope and the Create Vision Events permission.
Roboflow API key passed as a Bearer token.
The use case the filters belong to.
Must be unique in the use case, ignoring case. Leading and trailing spaces are trimmed.
Line 3 missesSaved filter created.
Invalid name or filters.
Insufficient permissions, or a device API key.
The use case does not exist or is archived.
The name is taken, or the use case already has 100 saved filters.
POST /vision-events/use-cases/{useCaseId}/saved-filters HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 241
{
"name": "Line 3 misses",
"filters": [
{
"category": "startDate",
"operator": "gte",
"value": "now-7d",
"label": "Start Date: 7 days ago"
},
{
"category": "customMetadata",
"field": "line_id",
"type": "string",
"operator": "eq",
"value": "3",
"label": "line_id: 3"
}
]
}{
"savedFilter": {
"id": "Yq3mT8vR2nKp",
"name": "Line 3 misses",
"filters": [
{
"category": "startDate",
"operator": "gte",
"value": "now-7d",
"label": "Start Date: 7 days ago"
},
{
"category": "customMetadata",
"field": "line_id",
"type": "string",
"operator": "eq",
"value": "3",
"label": "line_id: 3"
}
],
"createdBy": "text",
"createdAt": "2026-01-01T00:00:00.000Z",
"updatedBy": "text",
"updatedAt": "2026-01-01T00:00:00.000Z"
}
}Rename a saved filter, save new filters over it, or both. Saving over needs the vision-events:write scope. Renaming needs vision-events:manage, unless an OAuth token renames a filter its own user saved.
Roboflow API key passed as a Bearer token.
The use case the filter belongs to.
The saved filter ID.
Send name, filters, or both.
A new name. Must be unique in the use case, ignoring case.
Saved filter updated.
Invalid name or filters.
Insufficient permissions, or a device API key.
Saved filter not found.
The new name is taken, or the saved filter can no longer be read.
PATCH /vision-events/use-cases/{useCaseId}/saved-filters/{savedFilterId} HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 37
{
"name": "Line 3 misses, last 7 days"
}{
"savedFilter": {
"id": "Yq3mT8vR2nKp",
"name": "Line 3 misses",
"filters": [
{
"category": "startDate",
"operator": "gte",
"value": "now-7d",
"label": "Start Date: 7 days ago"
},
{
"category": "customMetadata",
"field": "line_id",
"type": "string",
"operator": "eq",
"value": "3",
"label": "line_id: 3"
}
],
"createdBy": "text",
"createdAt": "2026-01-01T00:00:00.000Z",
"updatedBy": "text",
"updatedAt": "2026-01-01T00:00:00.000Z"
}
}Delete a saved filter. Needs the vision-events:manage scope, unless an OAuth token deletes a filter its own user saved.
Roboflow API key passed as a Bearer token.
The use case the filter belongs to.
The saved filter ID.
Saved filter deleted.
Insufficient permissions, or a device API key.
The saved filter or its use case does not exist, or the use case is archived.
The saved filter can no longer be read. Save it again from the Search tab.
DELETE /vision-events/use-cases/{useCaseId}/saved-filters/{savedFilterId} HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"success": true
}파이썬 SDK
필터, 시간 범위, 페이지네이션을 사용해 비전 이벤트를 조회합니다.
단일 페이지 조회
사용하세요 query_vision_events() 를 사용해 결과의 단일 페이지를 가져오세요:
키워드 인수로 추가 필터를 전달할 수도 있습니다. 이는 API로 직접 전달됩니다:
수동 페이지 매김의 경우, 다음을 사용하세요 cursor 매개변수와 nextCursor 이전 응답의 값:
모든 결과를 통해 페이지 매김
사용하세요 query_all_vision_events() 일치하는 모든 이벤트를 자동으로 페이지 매김합니다. 한 번에 이벤트 한 페이지씩 반환합니다:
사용 가능한 필터, 연산자 및 응답 형식에 대한 전체 세부 정보는 다음을 참조하세요: REST API 레퍼런스.
MCP 서버
AI 에이전트를 MCP 서버 에 연결하면 다음 도구로 이벤트에 관한 질문에 답할 수 있습니다:
vision_events_query
필터와 페이지 매김을 사용하여 운영 환경의 비전 이벤트를 조회합니다.
vision_events_use_cases_list
워크스페이스에서 비전 이벤트 사용 사례를 나열합니다.
vision_events_custom_metadata_schema_get
사용 사례에 대해 검색된 사용자 지정 메타데이터 스키마를 가져옵니다.
마지막 업데이트
도움이 되었나요?