> 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/ko/monitoring-and-analytics/vision-events/query-events.md).
# 이벤트 조회
## 소개
이 페이지에서는 특정 [Vision Events](/deployment/ko/monitoring-and-analytics/vision-events.md) - 배포된 모델이 관찰한 내용의 타임스탬프 기록 - 을 Vision Events 대시보드에서 필터링하고 검색하거나 REST API를 통해 프로그래밍 방식으로 조회할 수 있습니다. 날짜 범위, 이벤트 유형, 디바이스, 스트림, 워크플로, 감지된 클래스 또는 피드백 상태로 결과를 좁혀 운영 동작을 감사하고 보고서를 작성하세요. 또한 [Roboflow Agent](https://docs.roboflow.com/agents/roboflow-agent) 이벤트에 대해 자연어로 질문할 수 있습니다.
## 웹 앱
### 이벤트 조회 및 필터링
Vision Events 대시보드의 필터를 사용하거나 REST API를 통해 프로그래밍 방식으로 특정 이벤트를 찾습니다.
#### 대시보드에서 이벤트 탐색
**사용 사례 선택**
Vision Events 페이지에서 사용 사례를 클릭하여 해당 이벤트를 봅니다. 이벤트는 최신순 역순으로 표시됩니다.
**이벤트 필터링**
결과를 좁히려면 이벤트 목록 상단의 필터 컨트롤을 사용하세요:
* **날짜 범위** - 시작 및 종료 타임스탬프
* **이벤트 유형** - quality\_check, inventory\_count, safety\_alert, custom, operator\_feedback
* **디바이스** - 디바이스 ID로 필터링
* **스트림** - 스트림 또는 카메라 ID로 필터링
* **워크플로** - 이벤트를 생성한 워크플로로 필터링
* **감지** - 감지된 객체 클래스로 필터링하며, 선택적으로 신뢰도 임계값을 지정할 수 있습니다
* **피드백 상태** - correct, incorrect, inconclusive 또는 피드백 없음
* **사용자 지정 메타데이터** - 사용자 지정 메타데이터의 모든 필드와 값으로 필터링
* **경고** - 수집 경고가 있었던 이벤트만 표시
또한 이벤트 세부 정보 사이드바의 값(예: 디바이스 ID, 스트림, 품질 검사 결과 또는 사용자 지정 메타데이터 값)을 클릭하여 빠르게 필터로 추가할 수 있습니다.
필터 칩은 편집할 수 있습니다. 활성 필터 칩을 클릭하면 제거했다가 다시 추가하지 않아도 값이나 연산자를 수정할 수 있습니다.
필터가 적용되면 **총 개수** 가 일치하는 이벤트 수가 결과 목록 상단에 표시됩니다. 이 개수는 이벤트 목록과 별도로 업데이트되므로, 이벤트가 아직 로드 중인 동안에도 필터와 일치하는 이벤트 수를 확인할 수 있습니다.
**이벤트 세부 정보 보기**
목록의 아무 이벤트나 클릭하여 전체 세부 정보를 봅니다:
* 소스 이미지와 출력 이미지
* 모든 소스 메타데이터(디바이스, 스트림, 워크플로)
* 신뢰도 점수가 포함된 객체 감지, 분류, 세분화
* 이벤트 유형별 데이터(예: 통과/실패 결과, 항목 수, 경고 심각도)
* 사용자 지정 메타데이터 키-값 쌍
**감지 그리기**
이벤트에 예측 데이터(객체 감지, 인스턴스 세분화 또는 키포인트)가 포함되어 있으면 이미지 위에 "감지 그리기" 체크박스가 나타납니다. 이를 활성화하면 소스 이미지 위에 신뢰도 점수가 포함된 바운딩 박스, 세분화 폴리곤, 레이블을 오버레이할 수 있습니다.
파이프라인이 원본 입력 이미지만 저장하고, 별도의 출력 이미지를 저장하지 않고 모델이 감지한 내용을 시각화하려는 경우 유용합니다.
{% hint style="info" %}
구분된 출력 이미지를 볼 때는 체크박스가 숨겨집니다. 출력 이미지에는 이미 감지가 렌더링되어 있기 때문입니다.
{% endhint %}
**자동 최종 확정 이벤트**
자동 최종 확정으로 표시된 이벤트는 동영상 업로드가 완료되기 전에 엣지 디바이스에서 자동으로 닫혔기 때문에 동영상이 없습니다. 이 이벤트에는 여전히 결과와 정지 이미지가 포함됩니다. 이벤트 카드에는 표시기가 나타나고, 세부 보기에는 최종 확정된 시간이 표시됩니다. 이는 다음을 통해 동기화된 이벤트에만 적용됩니다 [엣지 디바이스 백업](/deployment/ko/monitoring-and-analytics/vision-events/send-events.md#edge-device-backup).
### Agent에게 질문하기
직접 필터를 만드는 대신 자연어로 이벤트를 조회할 수 있습니다. 왼쪽 사이드바에서 [Roboflow Agent](https://docs.roboflow.com/agents/roboflow-agent) "Agent"를 클릭한 다음 사용 사례에 대해 질문하세요(예: "지난주 assembly-line-qa의 실패 건수는 몇 건이었나요?", "결함률은 시간에 따라 어떻게 변했나요?", "스트림당 평균 항목 수는 얼마인가요?").
또한 사용 사례에서 "AI로 분석"을 클릭할 수 있습니다. 이 버튼은 개요 및 검색 탭에 표시되며, 해당 사용 사례에 대한 질문이 입력된 새 탭에서 Agent를 엽니다. 검색 탭에서는 질문에 적용한 필터도 포함되므로, Agent는 보고 있는 것과 동일한 이벤트를 확인합니다.
Agent는 이벤트 데이터를 조회하여 답변하므로, 숫자는 이벤트에 실제로 포함된 내용을 반영합니다. 다음이 가능합니다:
* 시간 범위, 이벤트 유형 또는 결과와 일치하는 이벤트 수를 계산합니다.
* 시간에 따른 통과 및 실패율을 추적하고 결함률이 개선되는지 악화되는지 알려줍니다.
* 숫자 필드의 합계, 평균, 최소값, 최대값 또는 고유 값 개수를 구합니다.
* 이벤트 필드나 사용자 지정 메타데이터별로 총계를 그룹화하거나, 일 또는 주 단위로 버킷팅합니다.
질문이 작업 공간의 [보존 기간](/deployment/ko/monitoring-and-analytics/vision-events.md#data-retention)을 넘어가면, Agent는 0을 반환하는 대신 조회할 수 있는 가장 이른 날짜를 알려줍니다. 날짜 경계와 시간 버킷은 UTC를 사용합니다.
이벤트에 대해 질문하려면 "View Vision Events" [권한](https://docs.roboflow.com/platform/enterprise-features/role-based-access-control).
일회성 답변 대신 이메일로 정기적으로 보내는 요약본을 보려면 [요약 보고서](/deployment/ko/monitoring-and-analytics/vision-events/summary-reports.md).
## HTTP API
### API를 통해 이벤트 조회
쿼리 엔드포인트는 대시보드와 동일한 필터에 커서 기반 페이지 매김을 더해 지원합니다. 매개변수와 응답 필드의 전체 목록은 [Vision Events API 참조](/deployment/ko/monitoring-and-analytics/vision-events.md#http-api).
#### 기본 쿼리
```bash
curl -X POST "https://api.roboflow.com/vision-events/query" \\
-H "Content-Type: application/json" \\
-H "Authorization: Bearer YOUR_API_KEY" \\
-d '{
"useCaseId": "assembly-line-qa",
"startTime": "2026-03-01T00:00:00Z",
"endTime": "2026-03-31T23:59:59Z",
"limit": 25
}'
```
**응답:**
```json
{
"events": [
{
"eventId": "evt-789ghi",
"eventType": "quality_check",
"timestamp": "2026-03-30T14:30:00.000Z",
"deviceId": "factory-cam-01",
"streamId": "line-3",
"images": [],
"eventData": { "result": "fail" },
"customMetadata": {
"line_id": "line-3",
"shift": "morning",
"part_number": "PN-4421"
}
}
],
"nextCursor": "eyJ0cyI6IjIwMjYtMDMtMzAifQ==",
"hasMore": true
}
```
#### 페이지 매김
결과는 커서를 사용해 페이지 매김됩니다. 응답에 다음이 포함되어 있으면 `nextCursor` 값이 있고 `hasMore` 가 `true`이면, 다음 페이지를 가져오려면 다음 요청에 커서를 전달하세요:
```bash
curl -X POST "https://api.roboflow.com/vision-events/query" \\
-H "Content-Type: application/json" \\
-H "Authorization: Bearer YOUR_API_KEY" \\
-d '{
"useCaseId": "assembly-line-qa",
"limit": 25,
"cursor": "eyJ0cyI6IjIwMjYtMDMtMzAifQ=="
}'
```
다음이 될 때까지 계속 `hasMore` 가 `false`.
#### 이벤트 유형으로 필터링
단일 이벤트 유형을 조회:
```json
{
"useCaseId": "assembly-line-qa",
"eventType": "quality_check"
}
```
또는 여러 이벤트 유형(최대 20개):
```json
{
"useCaseId": "assembly-line-qa",
"eventTypes": ["quality_check", "operator_feedback"]
}
```
#### 피드백 상태로 필터링
사용 `feedbackStatus` 를 사용하여 운영자가 검토했는지와 어떻게 평가했는지에 따라 이벤트를 찾습니다:
```json
{
"useCaseId": "assembly-line-qa",
"feedbackStatus": ["incorrect", "none"]
}
```
유효한 값: `correct`, `incorrect`, `inconclusive`, `none`. 다음의 경우 `none` 아직 검토되지 않은 이벤트를 찾으세요.
#### 사용자 지정 메타데이터로 필터링
사용 `customMetadataFilters` 를 사용하여 사용자 지정 메타데이터 필드로 이벤트를 필터링합니다:
```json
{
"useCaseId": "assembly-line-qa",
"customMetadataFilters": [
{ "key": "line_id", "operator": "eq", "value": "line-3" },
{ "key": "shift", "operator": "eq", "value": "morning" }
]
}
```
### Vision Events 조회
필터, 시간 범위, 페이지 매김을 사용하여 Vision Events를 조회합니다. 이 엔드포인트는 이벤트 유형, 디바이스 컨텍스트, 감지 클래스, 사용자 지정 메타데이터, 이벤트별 필드로 필터링을 지원합니다.
**필수 범위:** `vision-events:read` 또는 `device:read`
{% openapi src="/files/07bb573a8b2a5a268b550bc4e2d87e5feae31c5d" path="/vision-events/query" method="post" %}
[openapi.yaml](https://1826078061-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoksNmwps1HmYr8TqHDnX%2Fuploads%2Fgit-blob-2afefc06c784ca78eb7ec96a99bee48f8a2daaa5%2Fopenapi.yaml?alt=media)
{% endopenapi %}
#### 요청 예시
```bash
curl -X POST "https://api.roboflow.com/vision-events/query" \\
-H "Authorization: Bearer YOUR_API_KEY" \\
-H "Content-Type: application/json" \\
-d '{
"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
}'
```
#### 요청 본문 매개변수
**필수 필드:**
* **`useCaseId`** (문자열): 이벤트를 조회할 사용 사례 ID입니다. 다음을 참조하세요 [사용 사례](/deployment/ko/monitoring-and-analytics/vision-events/use-cases.md) 에서 사용 사례 ID를 찾는 방법을 확인하세요.
**시간 범위 필터:**
* **`startTime`** (문자열, ISO 8601, 선택 사항): 시간 범위의 시작.
* **`endTime`** (문자열, ISO 8601, 선택 사항): 시간 범위의 끝.
**이벤트 유형 필터:**
* **`eventTypes`** (문자열 배열, 최대 20개, 선택 사항): 하나 이상의 이벤트 유형으로 필터링합니다.
**컨텍스트 필터:**
각 컨텍스트 필터는 다음을 가진 객체입니다 `operator` 및 `값`:
* **`deviceId`** (객체, 선택 사항): 디바이스로 필터링합니다. 연산자: `eq`, `neq`.
* **`streamId`** (객체, 선택 사항): 스트림으로 필터링합니다. 연산자: `eq`, `neq`.
* **`workflowId`** (객체, 선택 사항): 워크플로로 필터링합니다. 연산자: `eq`, `neq`.
* **`externalId`** (객체, 선택 사항): 외부 ID로 필터링합니다. 연산자: `eq`, `neq`.
```json
{
"deviceId": { "operator": "eq", "value": "camera-node-5" }
}
```
**감지 필터:**
* **`detection`** (객체, 선택 사항): 감지 클래스 이름으로 이벤트를 필터링하며, 선택적으로 감지별 신뢰도 임계값을 추가로 결합할 수 있습니다. 연산자: `eq`, `neq`, `in`, `not_in`. 해당하는 경우 `in` 및 `not_in`, 값으로 문자열 배열을 전달하세요(최대 50개).
* **`confidence`** (객체, 선택 사항): 감지별 신뢰도 임계값. 클래스 연산자와 함께 사용할 때만 지원됩니다. `eq` 및 `in` 클래스와 신뢰도는 동일한 감지에서 일치해야 합니다.
* **`operator`** (문자열): 다음 중 하나 `gt`, `gte`, `lt`, `lte`.
* **`값`** (숫자): 0과 1 사이의 신뢰도 임계값.
```json
{
"detection": { "operator": "in", "value": ["defect", "crack"] }
}
```
최소 신뢰도로 클래스로 필터링:
```json
{
"detection": {
"operator": "eq",
"value": "scratch",
"confidence": { "operator": "gte", "value": 0.8 }
}
}
```
{% hint style="info" %}
이 `detection` 필터의 이전 이름은 `detectionClass`였습니다. 이전 이름은 더 이상 허용되지 않습니다.
{% endhint %}
**이미지 및 경고 필터:**
* **`imageCount`** (객체, 선택 사항): 이벤트에 첨부된 이미지 수로 필터링합니다. 연산자: `eq`, `neq`, `gt`, `gte`, `lt`, `lte`.
* **`hasWarnings`** (불리언, 선택 사항): 수집 경고가 있는 이벤트와 없는 이벤트로 필터링합니다.
```json
{
"imageCount": { "operator": "gte", "value": 1 }
}
```
**사용자 지정 메타데이터 필터:**
* **`customMetadataFilters`** (배열, 최대 20개, 선택 사항): 사용자 지정 메타데이터 필드로 필터링합니다. 각 필터에는 다음이 있습니다:
* **`field`** (문자열): 메타데이터 필드 이름.
* **`operator`** (문자열): 비교 연산자.
* **`값`**: 비교 대상 값.
* **`type`** (문자열): 값 유형, 다음 중 하나 `string`, `number`, 또는 `boolean`.
유형별 사용 가능한 연산자:
| 유형 | 연산자 |
| --------- | ------------------------------------- |
| `string` | `eq`, `neq`, `in`, `not_in` |
| `number` | `eq`, `neq`, `gt`, `gte`, `lt`, `lte` |
| `boolean` | `eq`, `neq` |
**이벤트 필드 필터:**
* **`eventFieldFilters`** (배열, 최대 20개, 선택 사항): 이벤트별 필드로 필터링합니다. 각 필터에는 다음이 있습니다:
* **`column`** (문자열): 다음 중 하나 `result`, `location`, `item_count`, `item_type`, `alert_type`, `severity`, 또는 `feedback`.
* **`operator`** (문자열): 비교 연산자(`eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `in`, `not_in`).
* **`값`**: 비교 대상 값.
```json
{
"eventFieldFilters": [
{ "column": "result", "operator": "eq", "value": "fail" }
]
}
```
**페이지 매김:**
* **`cursor`** (문자열, 선택 사항): 다음 페이지를 가져오기 위한 이전 응답의 커서.
* **`limit`** (숫자, 선택 사항, 기본값 100, 최대 1000): 페이지당 반환할 이벤트 수.
#### 응답 예시
{% tabs %}
{% tab title="200" %}
```json
{
"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
}
]
}
],
"eventData": {
"result": "fail",
"externalId": "batch-001"
},
"customMetadata": {
"line": "A1",
"temperature": 72.5
}
}
],
"hasMore": false,
"lookbackDays": 14
}
```
때 `hasMore` 가 `true`, 다음을 사용하세요 `nextCursor` 값을 다음 요청에 사용하여 결과의 다음 페이지를 가져옵니다:
```json
{
"events": [...],
"hasMore": true,
"nextCursor": "eyJ0aW1lc3RhbXAiOiIyMDI0LTAxLTE1IiwiZXZlbnRJZCI6InFjLTAwMSJ9",
"lookbackDays": 14
}
```
{% endtab %}
{% tab title="400" %}
```json
{
"error": "Invalid query: useCaseId is required"
}
```
{% endtab %}
{% tab title="403" %}
```json
{
"error": "Insufficient permissions for this resource."
}
```
{% endtab %}
{% endtabs %}
## 파이썬 SDK
필터, 시간 범위, 페이지 매김을 사용하여 Vision Events를 조회합니다.
### 단일 페이지 조회
사용 `query_vision_events()` 를 사용하여 결과의 단일 페이지를 가져옵니다:
```python
import roboflow
roboflow.login()
rf = roboflow.Roboflow()
ws = rf.workspace()
page = ws.query_vision_events(
"a1b3c8e1", # 사용 사례 ID(필수)
event_type="quality_check", # 단일 이벤트 유형으로 필터링
start_time="2024-01-14T00:00:00Z", # ISO 8601 시작 시간
end_time="2024-01-15T23:59:59Z", # ISO 8601 종료 시간
limit=50, # 페이지당 최대 이벤트 수
)
for evt in page["events"]:
print(evt["eventId"], evt["eventData"] )
```
추가 필터도 키워드 인수로 전달할 수 있습니다. 이는 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"}
],
)
```
수동 페이지 매김의 경우 `cursor` 매개변수와 `nextCursor` 이전 응답의 값을 사용하세요:
```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", []))
```
### 모든 결과를 페이지 단위로 가져오기
사용 `query_all_vision_events()` 모든 일치하는 이벤트를 자동으로 페이지 단위로 가져오려면. 한 번에 이벤트 한 페이지씩 반환합니다:
```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")
```
사용 가능한 필터, 연산자, 응답 형식에 대한 전체 세부 정보는 다음을 참조하세요. [REST API 참조](#http-api).
## MCP 서버
AI 에이전트를 다음에 연결하세요 [MCP 서버](https://docs.roboflow.com/agents/mcp-server) 그러면 다음 도구를 사용해 이벤트에 대한 질문에 답할 수 있습니다: