Roboflow Docs

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 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. If your deployment has no route to the cloud, see Upload a Vision Event Bundle.

HTTP API

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

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

Create a Vision Event

posthttps://api.roboflow.com/vision-events

Create a single vision event.

Authorizations
AuthorizationstringRequired

Roboflow API key passed as a Bearer token.

Bodyapplication/json
eventIdstringRequired

Globally unique identifier. Use a UUID (v4).

eventTypestring · enumRequired
Possible values:quality_checkinventory_countsafety_alertcustomoperator_feedback
useCaseIdstringRequired

The use case this event belongs to.

timestampstringRequired

ISO 8601 timestamp. Must be between one year ago and tomorrow.

deviceIdstringOptional
streamIdstringOptional
workflowIdstringOptional
workflowVersionstringOptional
imagesobject · ImageReference[]Optional
Show properties
labelstringOptional
sourceIdstringOptional
inputSourceIdstringOptional
objectDetectionsobject · ObjectDetection[]Optional
Show properties
classstringRequired
xnumberRequired
ynumberRequired
widthnumberRequired
heightnumberRequired
confidencenumberRequired
classificationsobject · Classification[]Optional
Show properties
classstringRequired
confidencenumberRequired
instanceSegmentationsobject · InstanceSegmentation[]Optional
Show properties
classstringRequired
xnumberRequired
ynumberRequired
widthnumberRequired
heightnumberRequired
confidencenumberRequired
pointsnumber[][]Required
keypointsobject · Keypoint[]Optional
Show properties
classstringRequired
xnumberRequired
ynumberRequired
widthnumberRequired
heightnumberRequired
confidencenumberRequired
keypointsobject · KeypointEntry[]Required
metadataobject · ImageMetadataOptional

Key-value pairs describing this one image, such as a pass/fail verdict or a serial number. Keys must match [a-zA-Z0-9_ -]+, max 128 characters. Max 100 keys per image and 200 distinct keys per event. Values must be a string (max 1000 characters), a number, or a boolean. Nested objects and arrays are rejected.

Example: {"verdict":"pass","angle":42.5,"rechecked":true}
displayImagePositionintegerOptional
eventDataobjectRequired

Type-specific event data. Structure depends on eventType.

customMetadataobject · CustomMetadataOptional

Key-value pairs of custom metadata. Keys must match [a-zA-Z0-9_ -]+, max 100 characters. Max 100 keys per event.

Responses
201Event created successfully.application/json
eventIdstringOptional
createdbooleanOptional
warningsobject[]Optional
Show properties
typestringOptional
pathstringOptional
valuestringOptional
valueTypestringOptional
deprecationsstring[]Optional
400Validation error.application/json
errorstringOptional
403Insufficient permissions for this resource.application/json
errorstringOptional
post/vision-events
POST /vision-events HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: application/json

{
  "eventId": "text",
  "eventType": "quality_check",
  "useCaseId": "text",
  "timestamp": "text",
  "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
            }
          ]
        }
      ],
      "metadata": {
        "verdict": "pass",
        "angle": 42.5,
        "rechecked": true
      }
    }
  ],
  "displayImagePosition": 1,
  "eventData": {},
  "customMetadata": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  }
}
201Event created successfully.
{
  "eventId": "text",
  "created": true,
  "warnings": [
    {
      "type": "text",
      "path": "text",
      "value": "text",
      "valueType": "text"
    }
  ],
  "deprecations": [
    "text"
  ]
}

Example Request

curl -X POST "https://api.roboflow.com/vision-events" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "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
    }
  }'

Request Body Parameters

Each event must have a globally unique eventId. We recommend using a UUID (v4) to avoid collisions. Duplicate event IDs will overwrite previously ingested events.

Required fields:

  • eventId (string, max 256 characters): Globally unique identifier for the event. Use a UUID (v4).
  • eventType (string): One of quality_check, inventory_count, safety_alert, custom, or operator_feedback.
  • useCaseId (string, max 256 characters): The use case this event belongs to. See Use Cases for how to create and manage use cases.
  • timestamp (string, ISO 8601): When the event occurred. Must be between one year ago and tomorrow.
  • eventData (object): Type-specific event data. See Event Data Schemas below for the required structure per event type.

Optional fields:

  • deviceId (string, max 256): Identifier for the device that generated the event.
  • streamId (string, max 256): Identifier for the video stream.
  • workflowId (string, max 256): Identifier for the workflow that generated the event.
  • workflowVersion (string, max 64): Version of the workflow.
  • images (array, max 1000): Array of image objects with annotations. See Image Objects below.
  • displayImagePosition (number, 0-999): The index position of the image in the images array to use as the primary display image. For example, 0 for the first image, 1 for the second, and so on.
  • customMetadata (object, max 100 keys): Key-value pairs for custom metadata. See Custom Metadata below.
  • comment (string, max 1000): A note about the event. With operator_feedback, this holds the reviewer's note.

Event Data Schemas

The structure of eventData depends on the eventType:

{
  "result": "pass",
  "externalId": "batch-001"
}
  • result (string, optional): "pass" or "fail".
  • externalId (string, max 1000, optional): External reference ID.

Image Objects

To attach images to an event, you must first upload each image using the Upload a Vision Event Image endpoint to get a sourceId. Each image object in the images array represents an annotated (output) image. If you also want to associate the original unannotated (input) image, upload it separately and pass its sourceId as the inputSourceId.

{
  "label": "inspection-photo",
  "sourceId": "img-source-123",
  "inputSourceId": "camera-1",
  "objectDetections": [
    {
      "class": "defect",
      "x": 100,
      "y": 200,
      "width": 50,
      "height": 30,
      "confidence": 0.95
    }
  ],
  "classifications": [
    {
      "class": "damaged",
      "confidence": 0.87
    }
  ],
  "instanceSegmentations": [
    {
      "class": "crack",
      "x": 100,
      "y": 200,
      "width": 50,
      "height": 30,
      "confidence": 0.92,
      "points": [[100, 200], [120, 210], [110, 230]]
    }
  ],
  "metadata": {
    "verdict": "pass",
    "angle": 42.5
  },
  "keypoints": [
    {
      "class": "joint",
      "x": 100,
      "y": 200,
      "width": 50,
      "height": 30,
      "confidence": 0.88,
      "keypoints": [
        { "id": 0, "x": 105, "y": 205, "occluded": false },
        { "id": 1, "x": 115, "y": 215 }
      ]
    }
  ]
}

Image fields:

  • label (string, optional): A label for the image.
  • sourceId (string, optional): The sourceId returned from uploading the annotated image.
  • inputSourceId (string, optional): The sourceId returned from uploading the original unannotated (input) image.
  • objectDetections (array, max 1000, optional): Bounding box detections with class, x, y, width, height, and confidence (0-1).
  • classifications (array, max 1000, optional): Classification results with class and confidence (0-1).
  • instanceSegmentations (array, max 1000, optional): Segmentation results with bounding box fields plus points (array of [x, y] pairs, minimum 3).
  • keypoints (array, max 1000, optional): Keypoint detections with bounding box fields plus keypoints (array of objects with id, x, y, and optional occluded, minimum 1 keypoint per detection).
  • metadata (object, max 100 keys, optional): Key-value pairs about this one image. See Image Metadata below.

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 Custom Metadata instead.

Constraints:

  • Keys must match the pattern [a-zA-Z0-9_ -]+ (letters, digits, underscores, hyphens, and spaces), max 128 characters.
  • Up to 100 keys per image, and up to 200 distinct keys per event.
  • Values must be a string (max 1000 characters), a number, or a boolean. Nested objects and arrays are rejected.

Keys that break these rules 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. Image metadata is for display and discovery. You cannot filter on it in event queries yet.

Custom Metadata

You can attach up to 100 key-value pairs of custom metadata to each event. Custom metadata is queryable through the Query Vision Events endpoint.

Constraints:

  • Keys must match the pattern [a-zA-Z0-9_ -]+ (letters, digits, underscores, hyphens, and spaces), max 100 characters.
  • String values are limited to 1000 characters.
  • Number values support up to 6 decimal places.
  • Boolean values are supported.
{
  "customMetadata": {
    "production_line": "A1",
    "shift": "morning",
    "temperature": 72.5,
    "is_overtime": false
  }
}

Example Response

{
  "eventId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "created": true
}

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 (e.g., relatedEventId for operator_feedback)
  • Invalid values for eventData fields (e.g., 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.

{
  "eventId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "created": true,
  "warnings": [
    {
      "type": "any.required",
      "path": "eventData.relatedEventId",
      "value": null,
      "valueType": "object"
    }
  ]
}

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.

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.
  • 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.