# 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
* **Feedback status** — correct, incorrect, inconclusive, or no feedback
* **Custom metadata** — filter by any custom metadata field and value
* **Warnings** — show only events that had ingestion warnings

You can also click on values in the event detail sidebar (such as device ID, stream, quality check result, or custom metadata values) to quickly add them as filters.

Filter chips are editable -- click on any active filter chip to modify its value or operator without having to remove and re-add it.

When filters are applied, a **total count** of matching events is displayed at the top of the results list. This count updates independently of the event list, so you can see how many events match your filters even while events are still loading.

<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 Feedback Status

Use `feedbackStatus` to find events based on whether operators have reviewed them and how they were rated:

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

Valid values: `correct`, `incorrect`, `inconclusive`, `none`. Use `none` to find events that haven't been reviewed yet.

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


---

# Agent Instructions: 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:

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

The question should be specific, self-contained, and written in natural language.
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.