イベントを問い合わせる

ダッシュボードで Vision Events を検索、フィルタリング、閲覧したり、Agent に自然言語で質問したり、API 経由で問い合わせたりできます

概要

このページでは、特定の Vision Events - デプロイ済みモデルが観測した内容のタイムスタンプ付き記録 - を、Vision Events ダッシュボードでフィルタリングや検索を行うか、REST API を使ってプログラム的に取得できます。日付範囲、イベントタイプ、デバイス、ストリーム、ワークフロー、検出クラス、またはフィードバック状態で結果を絞り込み、本番動作を監査したりレポートを作成したりできます。さらに、 Roboflow Agent にイベントについて自然言語で質問することもできます。

Web アプリ

イベントのクエリとフィルタリング

Vision Events ダッシュボードのフィルターを使って特定のイベントを見つけるか、REST API 経由でプログラム的にクエリできます。

ダッシュボードでイベントを閲覧する

ユースケースを選択

Vision Events ページで、イベントを表示したいユースケースをクリックします。イベントは新しいものから順に表示されます。

イベントをフィルタリング

イベント一覧上部のフィルター操作で、次の条件で結果を絞り込めます:

日付範囲 - 開始および終了のタイムスタンプ
イベントタイプ - quality_check、inventory_count、safety_alert、custom、operator_feedback
デバイス - デバイスIDで絞り込む
ストリーム - ストリームまたはカメラIDで絞り込む
ワークフロー - イベントを生成したワークフローで絞り込む
検出 - 検出されたオブジェクトクラスで絞り込み、必要に応じて信頼度しきい値を指定します
フィードバック状態 - correct、incorrect、inconclusive、またはフィードバックなし
カスタムメタデータ - 任意のカスタムメタデータのフィールドと値で絞り込む
警告 - 取り込み警告があったイベントのみを表示

イベント詳細サイドバー内の値（デバイスID、ストリーム、品質チェック結果、カスタムメタデータ値など）をクリックして、すばやくフィルターとして追加することもできます。

フィルターチップは編集可能です。アクティブなフィルターチップをクリックすると、削除して再追加しなくても値や演算子を変更できます。

フィルターが適用されると、 合計件数 一致するイベント数が結果一覧の上部に表示されます。この件数はイベント一覧とは独立して更新されるため、イベントの読み込み中でもフィルターに一致するイベント数を確認できます。

イベント詳細を表示

一覧内の任意のイベントをクリックすると、詳細をすべて表示できます:

元画像と出力画像
すべてのソースメタデータ（デバイス、ストリーム、ワークフロー）
それぞれの信頼度スコア付きの物体検出、分類、セグメンテーション
イベントタイプ固有のデータ（例: 合否結果、アイテム数、アラートの重大度）
カスタムメタデータのキーと値のペア

検出結果を描画

イベントに予測データ（物体検出、インスタンスセグメンテーション、キーポイント）が含まれている場合、画像の上に「Draw Detections」チェックボックスが表示されます。これを有効にすると、元画像の上にバウンディングボックス、セグメンテーションポリゴン、信頼度スコア付きラベルを重ねて表示できます。

パイプラインが元の入力画像だけを保存していて、別の出力画像を保存せずにモデルが検出した内容を可視化したい場合に便利です。

個別の出力画像を表示している場合は、すでに検出結果が描画されているため、このチェックボックスは表示されません。

自動確定イベント

auto-finalized とマークされたイベントは、動画のアップロードが完了する前にエッジデバイス上で自動的にクローズされたため、動画がありません。イベントには結果と静止画は引き続き含まれています。イベントカードにはインジケーターが表示され、詳細ビューには確定時刻が表示されます。これは次を通じて同期されたイベントにのみ適用されますエッジデバイスバックアップ.

Agent に質問する

フィルターを手作業で作成する代わりに、自然言語でイベントをクエリできます。次を開いてください Roboflow Agent 左サイドバーの「Agent」をクリックし、ユースケースについて質問してください（例: 「先週、assembly-line-qa で失敗は何件ありましたか？」「不良率は時間とともにどう変化しましたか？」「ストリームごとの平均アイテム数はいくつですか？」）。

Agent はイベントデータをクエリして回答するため、数値はイベントに実際に含まれている内容を反映します。以下が可能です:

時間範囲、イベントタイプ、または結果に一致するイベント数を数える。
合格率と不合格率の推移を追跡し、不良率が改善しているか悪化しているかを伝える。
数値フィールドの合計、平均、最小、最大、または一意値の数を求める。
イベントフィールドやカスタムメタデータで合計をグループ化したり、日ごと・週ごとに集計したりする。

質問がワークスペースの保持期間を超える場合、Agent は 0 と答える代わりにクエリ可能な最も早い日付を知らせます。日付の境界と時間バケットには UTC を使用します。

イベントを質問するには「View Vision Events」権限.

単発の回答ではなく、定期配信のメール要約については、サマリーレポート.

HTTP API

API 経由でイベントをクエリする

クエリエンドポイントは、ダッシュボードと同じフィルターに加えて、カーソルベースのページネーションに対応しています。パラメータとレスポンスフィールドの完全な一覧は、 Vision Events 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"]
}

有効な値: 正しい, 誤り, 判断不能, なし。を使って なし まだレビューされていないイベントを見つけます。

カスタムメタデータでフィルタリング

使用する customMetadataFilters を使って独自のメタデータフィールドでイベントをフィルタリングします:

{
  "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

Query Vision Events

post

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

認可

Authorizationstring必須

Roboflow API key passed as a Bearer token.

本文

useCaseIdstring必須

The use case ID to query events for.

startTimestring · date-timeオプション

endTimestring · date-timeオプション

hasWarningsbooleanオプション

cursorstringオプション

limitinteger · 最小: 1 · 最大: 1000オプションDefault: 100

レスポンス

200

Query results.

application/json

hasMorebooleanオプション

nextCursorstringオプション

lookbackDaysintegerオプション

deprecationsstring[]オプション

400

Invalid query.

application/json

403

Insufficient permissions for this resource.

application/json

post/vision-events/query

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-12T11:19:17.321Z",
  "endTime": "2026-08-12T11:19:17.321Z",
  "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-12T11:19:17.321Z",
      "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、オプション）: 時間範囲の開始。
endTime （string、ISO 8601、オプション）: 時間範囲の終了。

イベントタイプフィルター:

eventTypes （文字列の配列、最大20件、オプション）: 1つ以上のイベントタイプで絞り込む。

コンテキストフィルター:

各コンテキストフィルターは、次の要素を持つオブジェクトです: operator と value:

deviceId （object、オプション）: デバイスで絞り込む。演算子: eq, neq.
streamId （object、オプション）: ストリームで絞り込む。演算子: eq, neq.
workflowId （object、オプション）: ワークフローで絞り込む。演算子: eq, neq.
externalId （object、オプション）: 外部IDで絞り込む。演算子: eq, neq.

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

検出フィルター:

detection （object、オプション）: 検出クラス名でイベントを絞り込み、必要に応じて検出ごとの信頼度しきい値と組み合わせます。演算子: eq, neq, in, not_in。については、 in と not_in値として文字列配列を渡します（最大50件）。
- confidence （object、オプション）: 検出ごとの信頼度しきい値。次と組み合わせた場合のみ対応: 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、オプション）: イベントに添付された画像の数で絞り込む。演算子: eq, neq, gt, gte, lt, lte.
hasWarnings （boolean、オプション）: 取り込み警告があるイベント、またはないイベントで絞り込む。

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

カスタムメタデータフィルター:

customMetadataFilters （配列、最大20件、オプション）: カスタムメタデータフィールドで絞り込みます。各フィルターには次があります:
- field （string）: メタデータフィールド名。
- operator （string）: 比較演算子。
- value: 比較対象の値。
- type （string）: 値の型。次のいずれか 文字列, 数値、または 真偽値.

型ごとに使用可能な演算子:

型

演算子

文字列

eq, neq, in, not_in

数値

eq, neq, gt, gte, lt, lte

真偽値

eq, neq

イベントフィールドフィルター:

eventFieldFilters （配列、最大20件、オプション）: イベント固有フィールドで絞り込みます。各フィルターには次があります:
- 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、オプション）: 次のページを取得するための、前回レスポンスのカーソル。
limit （number、オプション、既定100、最大1000）: 1ページあたりに返すイベント数。

レスポンス例

{
  "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
}

{
  "error": "無効なクエリ: useCaseId が必要です"
}

{
  "error": "このリソースに対する権限が不十分です。"
}

Python SDK

フィルター、時間範囲、ページネーションを使って Vision Events をクエリします。

単一ページクエリ

使用する query_vision_events() を使って結果の1ページを取得します:

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() 一致するすべてのイベントを自動的にページネーションして取得します。イベントを1ページずつ返します:

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 リファレンスを参照してください.

前へオペレーターのフィードバック次へイベントを送信

最終更新 4 日前

役に立ちましたか？