# 이벤트 조회

## 이벤트를 쿼리하고 필터링하기

Vision Events 대시보드의 필터를 사용해 특정 이벤트를 찾거나, REST API를 통해 프로그래밍 방식으로 쿼리할 수 있습니다.

### 대시보드에서 이벤트 탐색하기

#### 사용 사례 선택

Vision Events 페이지에서 사용 사례를 클릭해 해당 이벤트를 확인하세요. 이벤트는 최신 항목부터 역순으로 표시됩니다.

<figure><img src="https://3958014485-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M6S9nPJhEX9FYH6clfW%2Fuploads%2FLHsn28q2dYvdGrScCfC7%2Fimage.png?alt=media&#x26;token=f522aaab-16af-4979-925a-1d10997aafdf" alt="" width="375"><figcaption></figcaption></figure>

#### 이벤트 필터링

이벤트 목록 상단의 필터 컨트롤을 사용하여 다음 기준으로 결과를 좁힐 수 있습니다:

* **날짜 범위** — 시작 및 종료 타임스탬프
* **이벤트 유형** — quality\_check, inventory\_count, safety\_alert, custom, operator\_feedback
* **디바이스** — 디바이스 ID로 필터링
* **스트림** — 스트림 또는 카메라 ID로 필터링
* **워크플로우** — 이벤트를 생성한 워크플로우로 필터링
* **탐지 클래스** — 특정 탐지된 객체 클래스로 필터링
* **사용자 지정 메타데이터** — 모든 사용자 지정 메타데이터 필드와 값으로 필터링
* **경고** — 수집 경고가 있었던 이벤트만 표시

<figure><img src="https://3958014485-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M6S9nPJhEX9FYH6clfW%2Fuploads%2FkrZ4GYbY0ENZfG7tpnAX%2Fimage.png?alt=media&#x26;token=78c0fbc4-d9ce-47d6-a859-639311329eec" alt="" width="375"><figcaption></figcaption></figure>

#### 이벤트 세부 정보 보기

목록의 아무 이벤트나 클릭하여 전체 세부 정보를 확인하세요:

* 오버레이된 예측이 포함된 원본 이미지(탐지, 분류, 세그멘테이션)
* 모든 소스 메타데이터(디바이스, 스트림, 워크플로우)
* 이벤트 유형별 데이터(예: 통과/실패 결과, 항목 수, 경고 심각도)
* 사용자 지정 메타데이터 키-값 쌍

<figure><img src="https://3958014485-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M6S9nPJhEX9FYH6clfW%2Fuploads%2FQvgUZXvbdclpG1Ks3a4c%2Fimage.png?alt=media&#x26;token=3b0938bb-a1d0-43d9-bf47-b072be8b98a5" alt="" width="375"><figcaption></figcaption></figure>

### API를 통해 이벤트 쿼리하기

쿼리 엔드포인트는 대시보드와 동일한 필터를 지원하며, 커서 기반 페이지네이션도 제공합니다. 전체 파라미터 및 응답 필드 목록은 다음을 참조하세요: [Vision Events API Reference](https://docs.roboflow.com/developer/rest-api/vision-events).

#### 기본 쿼리

```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"]
}
```

#### 사용자 지정 메타데이터로 필터링

다음을 사용하세요 `customMetadataFilters` 를 사용하여 자체 메타데이터 필드로 이벤트를 필터링합니다:

```json
{
  "useCaseId": "assembly-line-qa",
  "customMetadataFilters": [
    { "key": "line_id", "operator": "eq", "value": "line-3" },
    { "key": "shift", "operator": "eq", "value": "morning" }
  ]
}
```