# Query Vision Events

Query vision events with filters, time ranges, and pagination. This endpoint supports filtering by event type, device context, detection classes, custom metadata, and event-specific fields.

**Required scope:** `vision-events:read` or `device:read`

{% openapi src="<https://1284666567-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fe5GEiPeDoFksvZv1vH3A%2Fuploads%2Fgit-blob-0e98238ab4157276fe00dee89f522ee5a021e711%2Fopenapi.yaml?alt=media>" path="/vision-events/query" method="post" %}
[openapi.yaml](https://1284666567-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fe5GEiPeDoFksvZv1vH3A%2Fuploads%2Fgit-blob-0e98238ab4157276fe00dee89f522ee5a021e711%2Fopenapi.yaml?alt=media)
{% endopenapi %}

### Example Request

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

### Request Body Parameters

**Required fields:**

* **`useCaseId`** (string): The use case ID to query events for. See [Use Cases](https://docs.roboflow.com/deploy/vision-events/use-cases) for how to find your use case ID.

**Time range filters:**

* **`startTime`** (string, ISO 8601, optional): Start of the time range.
* **`endTime`** (string, ISO 8601, optional): End of the time range.

**Event type filters:**

* **`eventTypes`** (array of strings, max 20, optional): Filter to one or more event types.

**Context filters:**

Each context filter is an object with `operator` and `value`:

* **`deviceId`** (object, optional): Filter by device. Operators: `eq`, `neq`.
* **`streamId`** (object, optional): Filter by stream. Operators: `eq`, `neq`.
* **`workflowId`** (object, optional): Filter by workflow. Operators: `eq`, `neq`.
* **`externalId`** (object, optional): Filter by external ID. Operators: `eq`, `neq`.

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

**Detection class filter:**

* **`detectionClass`** (object, optional): Filter events by detection class name. Operators: `eq`, `neq`, `in`, `not_in`. For `in` and `not_in`, pass an array of strings as the value (max 50).

```json
{
  "detectionClass": { "operator": "in", "value": ["defect", "crack"] }
}
```

**Image and warning filters:**

* **`imageCount`** (object, optional): Filter by number of images attached to the event. Operators: `eq`, `neq`, `gt`, `gte`, `lt`, `lte`.
* **`hasWarnings`** (boolean, optional): Filter to events that have or do not have ingestion warnings.

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

**Custom metadata filters:**

* **`customMetadataFilters`** (array, max 20, optional): Filter by custom metadata fields. Each filter has:
  * **`field`** (string): The metadata field name.
  * **`operator`** (string): Comparison operator.
  * **`value`**: The value to compare against.
  * **`type`** (string): The value type, one of `string`, `number`, or `boolean`.

Available operators by type:

| Type      | Operators                             |
| --------- | ------------------------------------- |
| `string`  | `eq`, `neq`, `in`, `not_in`           |
| `number`  | `eq`, `neq`, `gt`, `gte`, `lt`, `lte` |
| `boolean` | `eq`, `neq`                           |

**Event field filters:**

* **`eventFieldFilters`** (array, max 20, optional): Filter by event-specific fields. Each filter has:
  * **`column`** (string): One of `result`, `location`, `item_count`, `item_type`, `alert_type`, `severity`, or `feedback`.
  * **`operator`** (string): Comparison operator (`eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `in`, `not_in`).
  * **`value`**: The value to compare against.

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

**Pagination:**

* **`cursor`** (string, optional): Cursor from a previous response to fetch the next page.
* **`limit`** (number, optional, default 100, max 1000): Number of events to return per page.

### Example Response

{% tabs %}
{% tab title="200" %}

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

When `hasMore` is `true`, use the `nextCursor` value in your next request to retrieve the next page of results:

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

{% endtab %}

{% tab title="400" %}

```json
{
  "error": "Invalid query: useCaseId is required"
}
```

{% endtab %}

{% tab title="403" %}

```json
{
  "error": "Insufficient permissions for this resource."
}
```

{% endtab %}
{% endtabs %}