이벤트 쿼리

대시보드에서 Vision Events를 검색, 필터링, 탐색하고, 에이전트에게 자연어로 질문하거나 API를 통해 조회합니다

소개

이 페이지에서는 특정한 비전 이벤트 - 배포된 모델이 관찰한 내용에 대한 타임스탬프가 있는 기록 - 을 비전 이벤트 대시보드에서 필터링하고 검색하거나 REST API를 통해 프로그램적으로 조회할 수 있습니다. 날짜 범위, 이벤트 유형, 디바이스, 스트림, 워크플로, 감지된 클래스 또는 피드백 상태로 결과를 좁혀 운영 동작을 감사하고 보고서를 작성하세요. 또한 다음에게 질문할 수도 있습니다. Roboflow 에이전트 이벤트에 대해 자연어로 질문할 수 있습니다.

웹 앱

이벤트 쿼리 및 필터링

비전 이벤트 대시보드의 필터를 사용하여 특정 이벤트를 찾거나 REST API를 통해 프로그램적으로 쿼리하세요.

대시보드에서 이벤트 탐색

사용 사례 선택

비전 이벤트 페이지에서 사용 사례를 클릭하여 해당 이벤트를 보세요. 이벤트는 최신순 역순으로 표시됩니다.

이벤트 필터링

이벤트 목록 상단의 필터 컨트롤을 사용하여 다음 기준으로 결과를 좁히세요:

• 날짜 범위 - 시작 및 종료 타임스탬프

• 이벤트 유형 - quality_check, inventory_count, safety_alert, custom, operator_feedback

• 디바이스 - 디바이스 ID로 필터링

• 스트림 - 스트림 또는 카메라 ID로 필터링

• 워크플로 - 이벤트를 생성한 워크플로로 필터링

• 감지 - 감지된 객체 클래스로 필터링하며, 선택적으로 신뢰도 임계값을 설정할 수 있습니다

• 피드백 상태 - correct, incorrect, inconclusive 또는 피드백 없음

• 사용자 지정 메타데이터 - 임의의 사용자 지정 메타데이터 필드와 값으로 필터링

• 경고 - 수집 경고가 있었던 이벤트만 표시

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

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

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

이벤트 세부 정보 보기

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

• 원본 이미지 및 모든 출력 이미지

• 모든 원본 메타데이터(디바이스, 스트림, 워크플로)

• 신뢰도 점수가 포함된 객체 감지, 분류, 세그멘테이션

• 이벤트 유형별 데이터(예: 통과/실패 결과, 항목 수, 경고 심각도)

• 사용자 지정 메타데이터 키-값 쌍

감지 결과 그리기

이벤트에 예측 데이터(객체 감지, 인스턴스 세그멘테이션 또는 키포인트)가 포함되어 있으면 이미지 위에 "감지 결과 그리기" 체크박스가 나타납니다. 이를 활성화하면 원본 이미지 위에 바운딩 박스, 세그멘테이션 폴리곤, 그리고 신뢰도 점수가 포함된 레이블을 겹쳐 표시합니다.

파이프라인이 원본 입력 이미지만 저장하고 별도의 출력 이미지를 저장하지 않은 상태에서 모델이 감지한 내용을 시각화하고 싶을 때 유용합니다.

별도의 출력 이미지를 볼 때는 이미 감지 결과가 렌더링되어 있으므로 체크박스가 숨겨집니다.

자동 확정된 이벤트

자동 확정으로 표시된 이벤트는 비디오 업로드가 완료되기 전에 엣지 디바이스에서 자동으로 종료되어 비디오가 없습니다. 하지만 이벤트에는 결과와 정지 이미지가 그대로 포함됩니다. 이벤트 카드에는 표시가 나타나고, 세부 정보 보기에는 확정된 시간이 표시됩니다. 이는 다음을 통해 동기화된 이벤트에만 적용됩니다 엣지 디바이스 백업.

에이전트에게 질문하기

필터를 직접 만드는 대신 자연어로 이벤트를 쿼리할 수 있습니다. 다음을 여세요 Roboflow 에이전트 왼쪽 사이드바에서 "Agent"를 클릭한 다음, 사용 사례에 대해 질문하세요(예: "지난주 assembly-line-qa의 실패는 몇 건이었나요?", "결함률은 시간에 따라 어떻게 변했나요?", "스트림당 평균 항목 수는 얼마인가요?").

에이전트는 이벤트 데이터를 쿼리하여 답변하므로, 숫자는 이벤트에 실제로 포함된 내용을 반영합니다. 다음을 할 수 있습니다:

• 시간 범위, 이벤트 유형 또는 결과에 일치하는 이벤트 수를 계산합니다.

• 시간에 따른 통과율과 실패율을 추적하고 결함률이 개선되고 있는지 악화되고 있는지 알려줍니다.

• 숫자 필드의 합계, 평균, 최솟값, 최댓값 또는 고유 값 개수를 구합니다.

• 이벤트 필드나 사용자 지정 메타데이터별로 합계를 그룹화하거나, 일별 또는 주별로 버킷화합니다.

질문이 작업공간의 보존 기간을 넘어가면 에이전트는 0으로 답하지 않고 쿼리할 수 있는 가장 이른 날짜를 알려줍니다. 날짜 경계와 시간 버킷은 UTC를 사용합니다.

이벤트에 대해 질문하려면 "비전 이벤트 보기" 권한이 필요합니다.

일회성 답변 대신 정기 이메일 요약은 다음을 참조하세요 요약 보고서.

HTTP API

API를 통해 이벤트 쿼리

쿼리 엔드포인트는 대시보드와 동일한 필터에 더해 커서 기반 페이지네이션을 지원합니다. 매개변수와 응답 필드의 전체 목록은 다음을 참조하세요 비전 이벤트 API 참조.

기본 쿼리

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
  }'

응답:

{
  "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이면 다음 요청에 커서를 전달하여 다음 페이지를 가져오세요:

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.

이벤트 유형으로 필터링

단일 이벤트 유형을 쿼리하세요:

{
  "useCaseId": "assembly-line-qa",
  "eventType": "quality_check"
}

또는 여러 이벤트 유형을 쿼리하세요(최대 20개):

{
  "useCaseId": "assembly-line-qa",
  "eventTypes": ["quality_check", "operator_feedback"]
}

피드백 상태로 필터링

다음을 사용하세요 feedbackStatus 운영자가 검토했는지 여부와 평가 결과에 따라 이벤트를 찾습니다:

{
  "useCaseId": "assembly-line-qa",
  "feedbackStatus": ["incorrect", "none"]
}

유효한 값: correct, incorrect, inconclusive, none. 다음을 사용하여 none 아직 검토되지 않은 이벤트를 찾습니다.

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

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

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

비전 이벤트 쿼리

필터, 시간 범위, 페이지네이션을 사용해 비전 이벤트를 쿼리합니다. 이 엔드포인트는 이벤트 유형, 디바이스 컨텍스트, 감지 클래스, 사용자 지정 메타데이터, 이벤트별 필드로 필터링을 지원합니다.

필요한 스코프: vision-events:read 또는 device:read

Query Vision Events

post

Query vision events with filters, time ranges, and pagination.

Authorizations

bearerAuth

AuthorizationstringRequired

Roboflow API key passed as a Bearer token.

Body

application/json

useCaseIdstringRequired

The use case ID to query events for.

startTimestring · date-timeOptional

endTimestring · date-timeOptional

hasWarningsbooleanOptional

cursorstringOptional

limitinteger · min: 1 · max: 1000OptionalDefault: 100

Responses

200

Query results.

application/json

hasMorebooleanOptional

nextCursorstringOptional

lookbackDaysintegerOptional

deprecationsstring[]Optional

400

Invalid query.

application/json

403

Insufficient permissions for this resource.

application/json

post/vision-events/query

HTTPcURLJavaScriptPython

POST /vision-events/query HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 644

{
  "useCaseId": "text",
  "startTime": "2026-08-08T04:21:17.191Z",
  "endTime": "2026-08-08T04:21:17.191Z",
  "eventTypes": [
    "quality_check"
  ],
  "deviceId": {
    "operator": "eq",
    "value": "text"
  },
  "streamId": {
    "operator": "eq",
    "value": "text"
  },
  "workflowId": {
    "operator": "eq",
    "value": "text"
  },
  "externalId": {
    "operator": "eq",
    "value": "text"
  },
  "detection": {
    "operator": "eq",
    "value": "text",
    "confidence": {
      "operator": "gt",
      "value": 1
    }
  },
  "imageCount": {
    "operator": "eq",
    "value": 1
  },
  "hasWarnings": true,
  "customMetadataFilters": [
    {
      "field": "text",
      "operator": "eq",
      "value": "text",
      "type": "string"
    }
  ],
  "eventFieldFilters": [
    {
      "column": "result",
      "operator": "eq",
      "value": "text"
    }
  ],
  "cursor": "text",
  "limit": 100
}

{
  "events": [
    {
      "eventId": "text",
      "eventType": "quality_check",
      "useCaseId": "text",
      "timestamp": "2026-08-08T04:21:17.191Z",
      "deviceId": "text",
      "streamId": "text",
      "workflowId": "text",
      "workflowVersion": "text",
      "images": [
        {
          "label": "text",
          "sourceId": "text",
          "inputSourceId": "text",
          "objectDetections": [
            {
              "class": "text",
              "x": 1,
              "y": 1,
              "width": 1,
              "height": 1,
              "confidence": 1
            }
          ],
          "classifications": [
            {
              "class": "text",
              "confidence": 1
            }
          ],
          "instanceSegmentations": [
            {
              "class": "text",
              "x": 1,
              "y": 1,
              "width": 1,
              "height": 1,
              "confidence": 1,
              "points": [
                [
                  1
                ]
              ]
            }
          ],
          "keypoints": [
            {
              "class": "text",
              "x": 1,
              "y": 1,
              "width": 1,
              "height": 1,
              "confidence": 1,
              "keypoints": [
                {
                  "id": 1,
                  "x": 1,
                  "y": 1,
                  "occluded": true
                }
              ]
            }
          ]
        }
      ],
      "displayImagePosition": 1,
      "eventData": {},
      "customMetadata": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      }
    }
  ],
  "hasMore": true,
  "nextCursor": "text",
  "lookbackDays": 1,
  "deprecations": [
    "text"
  ]
}

예시 요청

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 (string): 이벤트를 쿼리할 사용 사례 ID입니다. 다음을 참조하세요 사용 사례 사용 사례 ID를 찾는 방법은 다음을 참조하세요.

시간 범위 필터:

• startTime (string, ISO 8601, optional): 시간 범위의 시작입니다.

• endTime (string, ISO 8601, optional): 시간 범위의 끝입니다.

이벤트 유형 필터:

• eventTypes (string 배열, 최대 20개, optional): 하나 이상의 이벤트 유형으로 필터링합니다.

컨텍스트 필터:

각 컨텍스트 필터는 다음을 가진 객체입니다 operator 그리고 value:

• deviceId (object, optional): 디바이스별로 필터링합니다. 연산자: eq, neq.

• streamId (object, optional): 스트림별로 필터링합니다. 연산자: eq, neq.

• workflowId (object, optional): 워크플로별로 필터링합니다. 연산자: eq, neq.

• externalId (object, optional): 외부 ID로 필터링합니다. 연산자: eq, neq.

{
  "deviceId": { "operator": "eq", "value": "camera-node-5" }
}

감지 필터:

• detection (object, optional): 감지 클래스 이름으로 이벤트를 필터링하며, 선택적으로 각 감지별 신뢰도 임계값과 결합할 수 있습니다. 연산자: eq, neq, in, not_in. 다음의 경우 in 그리고 not_in값으로 문자열 배열을 전달합니다(최대 50개).

  • confidence (object, optional): 각 감지별 신뢰도 임계값. 다음과 함께만 지원됩니다 eq 그리고 in 클래스 연산자. 클래스와 신뢰도는 같은 감지에서 일치해야 합니다.

    • operator (string): 다음 중 하나입니다 gt, gte, lt, lte.

    • value (number): 0과 1 사이의 신뢰도 임계값.

{
  "detection": { "operator": "in", "value": ["defect", "crack"] }
}

최소 신뢰도로 클래스를 필터링:

{
  "detection": {
    "operator": "eq",
    "value": "scratch",
    "confidence": { "operator": "gte", "value": 0.8 }
  }
}

다음 detection 필터는 이전에 다음 이름이었습니다 detectionClass. 이전 이름은 더 이상 허용되지 않습니다.

이미지 및 경고 필터:

• imageCount (object, optional): 이벤트에 첨부된 이미지 수로 필터링합니다. 연산자: eq, neq, gt, gte, lt, lte.

• hasWarnings (boolean, optional): 수집 경고가 있거나 없는 이벤트로 필터링합니다.

{
  "imageCount": { "operator": "gte", "value": 1 }
}

사용자 지정 메타데이터 필터:

• customMetadataFilters (array, 최대 20개, optional): 사용자 지정 메타데이터 필드로 필터링합니다. 각 필터에는 다음이 있습니다:

  • field (string): 메타데이터 필드 이름입니다.

  • operator (string): 비교 연산자입니다.

  • value: 비교 대상 값입니다.

  • type (string): 값 유형이며, 다음 중 하나입니다 문자열, 숫자, 또는 boolean.

유형별 사용 가능한 연산자:

유형	연산자
문자열	eq, neq, in, not_in
숫자	eq, neq, gt, gte, lt, lte
boolean	eq, neq

이벤트 필드 필터:

• eventFieldFilters (array, 최대 20개, optional): 이벤트별 필드로 필터링합니다. 각 필터에는 다음이 있습니다:

  • column (string): 다음 중 하나입니다 result, location, item_count, item_type, alert_type, severity, 또는 feedback.

  • operator (string): 비교 연산자 (eq, neq, gt, gte, lt, lte, in, not_in).

  • value: 비교 대상 값입니다.

{
  "eventFieldFilters": [
    { "column": "result", "operator": "eq", "value": "fail" }
  ]
}

페이지네이션:

• cursor (string, optional): 다음 페이지를 가져오기 위한 이전 응답의 커서입니다.

• limit (number, optional, 기본값 100, 최대 1000): 페이지당 반환할 이벤트 수입니다.

예시 응답

200

{
  "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 값을 다음 요청에 사용하여 다음 결과 페이지를 가져오세요:

{
  "events": [...],
  "hasMore": true,
  "nextCursor": "eyJ0aW1lc3RhbXAiOiIyMDI0LTAxLTE1IiwiZXZlbnRJZCI6InFjLTAwMSJ9",
  "lookbackDays": 14
}

400

{
  "error": "잘못된 쿼리: useCaseId가 필요합니다"
}

403

{
  "error": "이 리소스에 대한 권한이 부족합니다."
}

Python SDK

필터, 시간 범위, 페이지네이션을 사용해 비전 이벤트를 쿼리합니다.

단일 페이지 쿼리

다음을 사용하세요 query_vision_events() 를 사용해 결과의 단일 페이지를 가져옵니다:

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로 직접 전달됩니다:

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 이전 응답의 값과 함께:

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() 일치하는 모든 이벤트를 자동으로 페이지 단위로 가져옵니다. 한 번에 이벤트 한 페이지씩 반환합니다:

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"{len(all_events)}개의 이벤트를 찾았습니다")

사용 가능한 필터, 연산자, 응답 형식에 대한 전체 세부 정보는 다음을 참조하세요. REST API 참조.