Event Store

Store inference events on the edge device with automatic retention, storage limits, and optional cloud backup.

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://<device-ip>:8001
Interactive Swagger docs	http://<device-ip>:8001/docs

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:

1. Retention. Delete records older than RETENTION_DAYS.

2. Record limit. If the record count exceeds MAX_RECORDS, delete records over the limit, already-uploaded records first and then the oldest.

3. 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 its current_file_count is 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 404 responses when fetching images.

• Do not cache image IDs beyond a single session.

• Compare current_file_count against original_file_count on 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-here

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