> 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/roboflow/roboflow-ko/deploy/vision-events/query-events.md).

# Query Events

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

Vision Events 대시보드의 필터를 사용하거나 REST API를 통해 프로그래밍 방식으로 쿼리하여 특정 이벤트를 찾으세요.

### 대시보드에서 이벤트 찾아보기

#### 사용 사례 선택

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

<figure><img src="/files/470b2086abc3225b024ddc246bc2c030895d8cb0" alt="" width="375"><figcaption></figcaption></figure>

#### 이벤트 필터링

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

* **날짜 범위** — 시작 및 종료 타임스탬프
* **이벤트 유형** — quality\_check, inventory\_count, safety\_alert, custom, operator\_feedback
* **디바이스** — 디바이스 ID로 필터
* **스트림** — 스트림 또는 카메라 ID로 필터
* **워크플로** — 이벤트를 생성한 워크플로로 필터
* **감지** — 감지된 객체 클래스로 필터하며, 선택적으로 신뢰도 임계값을 지정할 수 있습니다
* **피드백 상태** — correct, incorrect, inconclusive 또는 피드백 없음
* **사용자 지정 메타데이터** — 모든 사용자 지정 메타데이터 필드와 값으로 필터
* **경고** — 수집 경고가 있었던 이벤트만 표시

이벤트 상세 사이드바의 값(예: 디바이스 ID, 스트림, 품질 검사 결과 또는 사용자 지정 메타데이터 값)을 클릭하여 필터로 빠르게 추가할 수도 있습니다.

필터 칩은 편집할 수 있습니다 -- 활성화된 필터 칩을 클릭하면 제거 후 다시 추가하지 않고도 값이나 연산자를 수정할 수 있습니다.

필터가 적용되면 **총 개수** 와 일치하는 이벤트 수가 결과 목록 상단에 표시됩니다. 이 개수는 이벤트 목록과 별도로 업데이트되므로, 이벤트가 아직 로드 중이더라도 필터에 일치하는 이벤트 수를 확인할 수 있습니다.

<figure><img src="/files/41b919230b476a7c403e0da7ad0b2f1ff1dd362c" alt="" width="375"><figcaption></figcaption></figure>

#### 이벤트 상세 보기

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

* 원본 이미지와 모든 출력 이미지
* 모든 원본 메타데이터(디바이스, 스트림, 워크플로)
* 신뢰도 점수가 포함된 객체 감지, 분류 및 세그멘테이션
* 이벤트 유형별 데이터(예: 합격/불합격 결과, 항목 수, 경고 심각도)
* 사용자 지정 메타데이터의 키-값 쌍

**Draw Detections**

이벤트에 예측 데이터(객체 감지, 인스턴스 세그멘테이션 또는 키포인트)가 포함된 경우 이미지 위에 "Draw Detections" 체크박스가 표시됩니다. 이를 활성화하면 바운딩 박스, 세그멘테이션 폴리곤, 그리고 신뢰도 점수가 포함된 레이블이 원본 이미지 위에 오버레이됩니다.

이는 파이프라인이 원본 입력 이미지만 저장하고 별도의 출력 이미지를 저장하지 않을 때, 모델이 무엇을 감지했는지 시각화하는 데 유용합니다.

{% hint style="info" %}
별도의 출력 이미지를 볼 때는 이미 감지가 렌더링되어 있으므로 이 체크박스는 숨겨집니다.
{% endhint %}

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

#### 피드백 상태로 필터링

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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.roboflow.com/roboflow/roboflow-ko/deploy/vision-events/query-events.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.