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

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

curl -L \
  --request POST \
  --url 'https://api.roboflow.com/vision-events' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{
  "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"
  }
}'

const response = await fetch("https://api.roboflow.com/vision-events", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_SECRET_TOKEN",
    "Content-Type": "application/json",
    "Accept": "application/json"
  },
  body: JSON.stringify({
    "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"
    }
  })
});

const data = await response.json();
console.log(data);

import requests

url = "https://api.roboflow.com/vision-events"
headers = {
    "Authorization": "Bearer YOUR_SECRET_TOKEN",
    "Content-Type": "application/json",
    "Accept": "application/json"
}
payload = {
  "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"
  }
}

response = requests.post(url, headers=headers, json=payload)
print(response.json())

Response

{
  "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.

{
  "location": "warehouse-a",
  "itemCount": 42,
  "itemType": "pallets",
  "externalId": "inv-2024-001"
}

location (string, max 1000, optional): Where the count was taken.
itemCount (integer, >= 0, optional): Number of items counted.
itemType (string, max 1000, optional): Type of item counted.
externalId (string, max 1000, optional): External reference ID.

{
  "alertType": "no_hardhat",
  "severity": "high",
  "description": "Worker detected without required PPE in zone B3.",
  "externalId": "alert-2024-001"
}

alertType (string, max 256, optional): Type of alert (alphanumeric, underscores, and dashes).
severity (string, optional): "low", "medium", or "high".
description (string, max 10000, optional): Description of the alert.
externalId (string, max 1000, optional): External reference ID.

{
  "value": "Custom event data as a string",
  "externalId": "custom-2024-001"
}

value (string, max 10000, optional): Freeform event data.
externalId (string, max 1000, optional): External reference ID.

{
  "relatedEventId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "feedback": "incorrect"
}

relatedEventId (string, required): The event ID (UUID) of the event this feedback is about.
feedback (string, required): "correct", "incorrect", or "inconclusive".

The reviewer's note goes in the top-level comment field, not in eventData.

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
}

{
  "error": "eventType is required"
}

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

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.