Batch Create Vision Events

Record up to 100 Vision Events in a single request to ingest many observations at once.

About

This endpoint records multiple Vision Events in a single request, up to 100 at a time. Use it when a deployment needs to ingest many observations at once, which is more efficient than creating events individually. To record a single event, see Create a Vision Event.

HTTP API

Create up to 100 vision events in a single request. This is more efficient than creating events individually when you need to ingest multiple events at once.

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

Batch Create Vision Events

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

Create up to 100 vision events in a single request.

Authorizations

AuthorizationstringRequired

Roboflow API key passed as a Bearer token.

Bodyapplication/json

eventsobject · VisionEvent[]Required

Show properties

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

classificationsobject · Classification[]Optional

instanceSegmentationsobject · InstanceSegmentation[]Optional

keypointsobject · Keypoint[]Optional

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

201Events created successfully.application/json

createdintegerOptional

eventIdsstring[]Optional

deprecationsstring[]Optional

400Validation error.application/json

errorstringOptional

403Insufficient permissions for this resource.application/json

errorstringOptional

post/vision-events/batch

POST /vision-events/batch HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: application/json

{
  "events": [
    {
      "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/batch' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{
  "events": [
    {
      "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/batch", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_SECRET_TOKEN",
    "Content-Type": "application/json",
    "Accept": "application/json"
  },
  body: JSON.stringify({
    "events": [
      {
        "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/batch"
headers = {
    "Authorization": "Bearer YOUR_SECRET_TOKEN",
    "Content-Type": "application/json",
    "Accept": "application/json"
}
payload = {
  "events": [
    {
      "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

{
  "created": 1,
  "eventIds": [
    "text"
  ],
  "deprecations": [
    "text"
  ]
}

Example Request

curl -X POST "https://api.roboflow.com/vision-events/batch" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {
        "eventId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
        "eventType": "quality_check",
        "useCaseId": "a1b3c8e1",
        "timestamp": "2024-01-15T10:30:00Z",
        "eventData": {
          "result": "pass"
        }
      },
      {
        "eventId": "9c4d6a2e-81f3-4b7a-bc9e-3f1a2d4e5c6b",
        "eventType": "quality_check",
        "useCaseId": "a1b3c8e1",
        "timestamp": "2024-01-15T10:31:00Z",
        "eventData": {
          "result": "fail"
        }
      }
    ]
  }'

Request Body Parameters

events (array, required, max 100): An array of event objects. Each event follows the same schema as the Create a Vision Event endpoint.

To include images in your events, first upload each image using the Upload a Vision Event Image endpoint, then reference the returned sourceId in the image object. See Image Objects for details.

Example Response

{
  "created": 2,
  "eventIds": ["f47ac10b-58cc-4372-a567-0e02b2c3d479", "9c4d6a2e-81f3-4b7a-bc9e-3f1a2d4e5c6b"]
}

{
  "error": "Batch size exceeds maximum of 100 events"
}

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

The response may also include a warnings object containing per-event validation warnings (keyed by event index), and a deprecations array if deprecated field names were used. See Validation and Warnings for details.

Python SDK

Create multiple vision events in a single request. The server allows up to 100 events per batch.

import roboflow

roboflow.login()

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

result = ws.write_vision_events_batch([
    {
        "eventId": "e5f6a7b8-c3d4-4e5f-a0b1-c2d3e4f5a6b7",
        "eventType": "quality_check",
        "useCaseId": "a1b3c8e1",
        "timestamp": "2024-01-15T10:00:00Z",
        "eventData": {"result": "pass"},
    },
    {
        "eventId": "f6a7b8c9-d4e5-4f6a-b1c2-d3e4f5a6b7c8",
        "eventType": "quality_check",
        "useCaseId": "a1b3c8e1",
        "timestamp": "2024-01-15T10:01:00Z",
        "eventData": {"result": "fail"},
        "customMetadata": {"line": "A1"},
    },
])

print(result["created"])    # Number of events created
print(result["eventIds"])   # List of created event IDs

Each event in the list follows the same schema as a single event. For full details on event schemas and validation behavior, see the REST API reference.