# Query Events

## Query and Filter Events

Find specific events using filters in the Vision Events dashboard or query them programmatically via the REST API.

### Browse Events in the Dashboard

#### Select a Use Case

From the Vision Events page, click on a Use Case to view its events. Events are displayed in reverse chronological order.

<figure><img src="https://662926385-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>

#### Filter Events

Use the filter controls at the top of the events list to narrow results by:

* **Date range** — start and end timestamps
* **Event type** — quality\_check, inventory\_count, safety\_alert, custom, operator\_feedback
* **Device** — filter by device ID
* **Stream** — filter by stream or camera ID
* **Workflow** — filter by the workflow that generated events
* **Detection class** — filter by a specific detected object class
* **Custom metadata** — filter by any custom metadata field and value
* **Warnings** — show only events that had ingestion warnings

<figure><img src="https://662926385-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>

#### View Event Details

Click on any event in the list to view its full details:

* The original image with overlaid predictions (detections, classifications, segmentations)
* All source metadata (device, stream, workflow)
* Event-type-specific data (e.g. pass/fail result, item count, alert severity)
* Custom metadata key-value pairs

<figure><img src="https://662926385-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>

### Query Events via the API

The query endpoint supports the same filters as the dashboard, plus cursor-based pagination. For the full list of parameters and response fields, see the [Vision Events API Reference](https://docs.roboflow.com/developer/rest-api/vision-events).

#### Basic Query

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

**Response:**

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

#### Pagination

Results are paginated using a cursor. If the response includes a `nextCursor` value and `hasMore` is `true`, pass the cursor in your next request to retrieve the next page:

```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=="
  }'
```

Continue until `hasMore` is `false`.

#### Filter by Event Type

Query a single event type:

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

Or multiple event types (max 20):

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

#### Filter by Custom Metadata

Use `customMetadataFilters` to filter events by your own metadata fields:

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