> For the complete documentation index, see [llms.txt](https://docs.roboflow.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.roboflow.com/deployment/monitoring-and-analytics/vision-events/create-a-vision-event.md).

# Create a Vision Event

Record a single Vision Event via the HTTP API to log an observation from your deployed model.

## About

A [Vision Event](https://docs.roboflow.com/deployment/monitoring-and-analytics/vision-events.md) is a timestamped record of something your deployed computer vision model observed - for example a detected defect or an inventory count - along with optional images, predictions, and custom metadata. This page shows how to record a single event so it becomes part of your searchable, filterable production history. To ingest many events at once, use [Batch Create Vision Events](https://docs.roboflow.com/deployment/monitoring-and-analytics/vision-events/batch-create-vision-events.md). If your deployment has no route to the cloud, see [Upload a Vision Event Bundle](https://docs.roboflow.com/deployment/monitoring-and-analytics/vision-events/upload-a-vision-event-bundle.md).

## HTTP API

Create a single vision event to record an observation from your computer vision deployment.

**Required scope:** `vision-events:write` or `device:update`

{% openapi src="/files/sCDP9kVopV4JkkRK7GDd" path="/vision-events" method="post" %}
[openapi.yaml](https://1583372177-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoksNmwps1HmYr8TqHDnX%2Fuploads%2Fgit-blob-0988c6c6c600d725f72d1ecfe0cbeba9b717363f%2Fopenapi.yaml?alt=media)
{% endopenapi %}

### Image Metadata

Use `metadata` on an image object to record values that belong to that image alone, such as a pass/fail verdict, a serial number, or a camera angle. Values are shown with the image in the event detail view. To attach values that describe the whole event, use `customMetadata` instead.

Keys that break the `metadata` limits are dropped and reported in the `warnings` array. The rest of the image is still stored.

To see which keys your events use, call [Get Image Metadata Schema](https://docs.roboflow.com/deployment/monitoring-and-analytics/vision-events/get-image-metadata-schema.md). To filter events by these keys, use `imageMetadataFilters` in [Query Events](https://docs.roboflow.com/deployment/monitoring-and-analytics/vision-events/query-events.md#query-vision-events).

### Validation and Warnings

The Vision Events API uses eager ingestion. Only the four required fields (`eventId`, `eventType`, `useCaseId`, `timestamp`) are strictly validated. If these pass, the event is always accepted and stored, even if other fields contain errors.

Any issues with non-required fields are returned as a `warnings` array in the response rather than causing a rejection. This includes:

* Missing required fields within `eventData` (ex: `relatedEventId` for `operator_feedback`)
* Invalid values for `eventData` fields (ex: a wrong enum value for `severity`)
* Unrecognized fields that are not part of the schema

When warnings are present, the invalid `eventData` is stored as an empty object `{}`, but the event itself is still created.

The response may also include a `deprecations` array if deprecated field names were used.

## Python SDK

Create a single vision event to record an observation from your computer vision deployment.

```python
import roboflow

roboflow.login()

rf = roboflow.Roboflow()
ws = rf.workspace()

ws.write_vision_event({
    "eventId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "eventType": "quality_check",
    "useCaseId": "a1b3c8e1",
    "timestamp": "2024-01-15T10:30:00Z",
    "eventData": {
        "result": "fail",
        "externalId": "batch-001",
    },
    "customMetadata": {
        "line": "A1",
        "operator": "John Doe",
        "temperature": 72.5,
    },
})
```

The event payload is passed directly to the server with no client-side validation, so new event types and fields work without an SDK update.

**Required fields:**

* **`eventId`** (string, max 256 characters): Globally unique identifier. Use a UUID (v4).
* **`eventType`** (string): One of `quality_check`, `inventory_count`, `safety_alert`, `custom`, or `operator_feedback`.
* **`useCaseId`** (string): The use case this event belongs to.
* **`timestamp`** (string, ISO 8601): When the event occurred.

**Optional fields:**

* **`eventData`** (dict): Type-specific event data.
* **`deviceId`**, **`streamId`**, **`workflowId`** (string): Context identifiers.
* **`images`** (list): Image objects with annotations. See [Upload a Vision Event Image](https://docs.roboflow.com/deployment/monitoring-and-analytics/vision-events/upload-a-vision-event-image.md#python-sdk).
* **`videos`** (list): Video objects. Get each `sourceId` from [Upload a Vision Event Video](https://docs.roboflow.com/deployment/monitoring-and-analytics/vision-events/upload-a-vision-event-video.md#http-api).
* **`customMetadata`** (dict): Up to 100 key-value pairs of custom metadata.
* **`comment`** (string): A note about the event, mainly used with `operator_feedback`.

For the full event schema, event data structures per type, and image annotation formats, see the [REST API reference](#http-api).
