The Event Store is an edge container service that records events produced by inference pipelines on the device. It holds inspection results, quality checks, safety alerts, and other Workflow outputs locally, serves them back over a REST API, and manages its own disk usage so a device never fills up.
Events written to the Event Store can also be backed up to Roboflow as Vision Events for long-term storage and analysis.
Event Store is available exclusively for Enterprise customers. Contact the Roboflow sales team to learn more.
Connection Details
Replace <device-ip> with the IP address shown on the device page in Deployment Manager.
| Purpose | Address |
|---|---|
| REST API | http:// |
| Interactive Swagger docs | http:// |
Port 8001 serves both over HTTP. See Event Store REST API for the endpoint reference.
To see live capacity and usage history for a device without calling the API, use View Event Store Status.
Storage Settings
Configure these from the Event Store card on the device's Configuration tab. Each maps to an environment variable on the service.
| Setting | Variable | Default | Description |
|---|---|---|---|
| "Retention Days" | RETENTION_DAYS | 1 | Events older than this many days are deleted. |
| "Max Records" | MAX_RECORDS | 1000000 | Maximum number of events kept. The oldest are removed once exceeded. |
| "Max Record Size" | MAX_RECORD_SIZE_BYTES | 524288 (512 KB) | Maximum size of a single event record. Larger events are rejected. |
| "Max Storage" | MAX_STORAGE_BYTES | 5368709120 (5 GB) | Total disk limit for stored files. Cleanup prunes files as usage approaches this limit. |
| "Cleanup Interval" | CLEANUP_INTERVAL_SECONDS | 300 | How often automatic cleanup runs. |
Additional variables:
| Variable | Default | Description |
|---|---|---|
PORT | 8001 | HTTP port for the API. |
DATA_DIR | /data | Data storage directory on the device. |
CONSISTENCY_CHECK_INTERVAL | 12 | Run a consistency check every N cleanups (roughly hourly at the default cleanup interval). |
API_KEY | none | Optional API key. See Authentication. |
Automatic Cleanup
Cleanup runs on a dedicated background thread, so it never blocks API requests. Each scheduled pass runs three steps in order:
- Retention. Delete records older than
RETENTION_DAYS. - Record limit. If the record count exceeds
MAX_RECORDS, delete records over the limit, already-uploaded records first and then the oldest. - Storage limit. As stored files approach
MAX_STORAGE_BYTES, delete image files, already-uploaded files first and then the oldest. The parent record is preserved and itscurrent_file_countis decremented.
Every CONSISTENCY_CHECK_INTERVAL cleanups the service also reconciles the database against the filesystem. It removes orphaned files on disk that have no matching database record, using a 10 minute grace period so in-flight writes are not touched, and removes dangling database records whose file is already gone.
You can also trigger a pass immediately with POST /admin/cleanup. See Administration.
Image Ephemerality
Image IDs returned by the API are inherently short-lived. An ID that resolved a minute ago can 404 after a cleanup pass, and that is by design on storage-constrained edge hardware.
- Handle
404responses when fetching images. - Do not cache image IDs beyond a single session.
- Compare
current_file_countagainstoriginal_file_counton an event to tell whether its files were cleaned up.
Draft Events and Video
A pipeline can save an event immediately and attach a video a few seconds later, once encoding finishes. Create the event with draft: true, upload the video when it is ready, then finalize the event. Events created without draft are finalized on creation, so existing pipelines are unaffected.
Until an event is finalized it is skipped by cloud upload. It is also protected from cleanup, but only while cloud upload is enabled on the service; with cloud upload off, a draft is as deletable as any other record.
| Setting | Variable | Default | Description |
|---|---|---|---|
| "Auto-finalize Drafts After" | DRAFT_AUTO_FINALIZE_SECONDS | 3600 | A draft whose video never arrives is force-finalized after this many seconds so it can back up and be cleaned up. |
| "Max Video Upload Size" | MAX_VIDEO_UPLOAD_BYTES | 1073741824 (1 GB) | Largest single video that can be attached to an event. |
Setting DRAFT_AUTO_FINALIZE_SECONDS to 0 disables the sweep. Drafts from a producer that never calls finalize then accumulate and, with cloud backup on, can fill the store and block new writes with HTTP 529 until the store is reset.
Per-Image Metadata and Local-Only Files
Pipelines can attach extra data to an event that stays on the device and is never uploaded to the cloud.
Per-image metadata is a small single-level object of key/value data attached to an individual image, such as a verdict, serial number, or angle label. It is stored with the record and returned by the API, but it is not queryable and is excluded from backup. METADATA_MAX_VALUE_LENGTH (default 1000) caps the length of a string value.
Local-only files are arbitrary files attached to an event, such as inspection blobs, thumbnails, or JSON. There is no content-type restriction, and MAX_LOCAL_ONLY_FILE_UPLOAD_BYTES (default 104857600, 100 MB) caps each upload. Files can only be attached while the event is still a draft, so the pipeline must create the event with draft: true, attach the file, then finalize.
Both are described in detail in the REST API reference.
Cloud Backup
When Vision Events backup is enabled on the device, finalized events are uploaded to Roboflow. Two modes are available:
- Records and Files uploads event metadata along with the associated image files.
- Records Only uploads event metadata and leaves images on the device, which uses less bandwidth.
Per-image metadata and local-only files are never uploaded in either mode.
See Send Events for enabling backup and querying the results in Roboflow.
Upload Reliability
Failed uploads are retried. "Upload Abandonment Policy" controls what happens to a record the server keeps rejecting.
| Policy | Variable value | Behavior |
|---|---|---|
| Never abandon | NEVER_ABANDON (default) | Records retry forever until they succeed. Safest for data, but a device filling with stuck records starts rejecting new writes with HTTP 529 rather than dropping unuploaded ones. |
| Abandon after max attempts | ABANDON_AFTER_MAX_ATTEMPTS | After UPLOAD_MAX_ATTEMPTS content-error attempts (default 10) a record is marked abandoned and becomes a preferred candidate for storage cleanup. Use this if losing persistently failing records is better than blocking new writes. |
Only content-style 4xx responses from the server (ex: 400, 413, 422) advance the attempt counter. All 5xx responses, timeouts, network errors, and 401, 403, 404, 408, and 429 are treated as transient and retry regardless of policy.
MIN_UPLOAD_IMAGE_BYTES (default 1) skips images smaller than the given size before upload. Corrupt but non-empty images currently come back as 5xx from the server and so retry forever under either policy. Raising this value above typical corruption sizes is the workaround.
Authentication
API key authentication is optional and off by default. Set API_KEY on the service to turn it on, after which every endpoint except /health requires the X-API-Key header.
environment:
- API_KEY=your-secret-api-key-herecurl -H "X-API-Key: your-secret-api-key-here" \
http://<device-ip>:8001/v2/events/latest/query/health stays reachable without authentication so monitoring systems and load balancers can poll it.