Snaps
Getting Started
- Create the
EventsManageronce (for example, next to your pipeline / device setup). - Keep a reference to it in your main application class or context.
- Call
sendSnap()whenever you want to upload visual data to Luxonis Hub.
| Parameter | Description | Example |
|---|---|---|
Name | The primary identifier for a snap | car_detected, gate_open, image |
Files | Attachments uploaded with the snap | ImgFrame, ImgDetections |
Tags (Optional) | Additional filters for grouping and filtering | dataset_collection, Dataset 1, Location 72, Assembly Line 17 |
Extras (Optional) | Additional filters for grouping and filtering | Car brand:volvo, State: open, Location: New York |
Success Callback (Optional) | Callback invoked after a successful upload attempt | on_success |
Failure Callback (Optional) | Callback invoked after a failed upload attempt | on_failure |
Snap Limits
| Field | Rule |
|---|---|
Name | 1–56 characters (required) |
Files | Max 20 files per snap (Min 1 required) |
Tags | Max 20 tags; each 1–56 characters |
Extras | Max 25 entries; extras.key 1–40 characters; extras.value 0–100 characters |
- Maximum file size
- Remaining storage
- Hourly limits for file uploads (number of files and bandwidth)
- Hourly limits for events and snaps sent
Note: CallingsendSnap()only validates basic parameters and queues the snap for upload. It does not guarantee that the snap has been sent to the Hub.sendSnap()returns a local snap ID (string) when the snap is queued successfully, andNone/nulloptwhen it is not. A successfully queued snap does not confirm delivery or file uploads. To be notified when the upload attempt finishes, passsuccessCallbackandfailureCallbackarguments tosendSnap().
Authentication
oakctl to run your application, the authentication is handled on your behalf. You do not provide an API key yourself.For oakctl run-script this uses the team you logged into using oakctl hub login. For oakctl app run this uses the team where the device is connected.To send snaps, your team's API Key must be defined. This is typically set using the environment variable DEPTHAI_HUB_API_KEY or inside your application using the EventsManager's setToken() method. When running in standalone mode and adopted to Hub, this environment variable is pre-populated.API Key good practices with practical examples can be found here.Sending Snaps with ImgFrames and ImgDetections
Python
C++
Python
Python
1# Create the EventsManager instance
2eventMan = dai.EventsManager()
3
4# Send snap with ImgFrame and ImgDetections
5localSnapID = eventMan.sendSnap(
6 name="snap_name",
7 fileTag="file_tag",
8 imgFrame=inImgFrame,
9 imgDetections=inImgDetections,
10 tags=["examples", "python"],
11 extras={"confidence": "0.75", "location": "01"},
12 successCallback=uploadSuccessCallback,
13 failureCallback=uploadFailureCallback
14)Python
C++
Python
Python
1# Create the EventsManager instance
2eventMan = dai.EventsManager()
3
4# Send snap with ImgFrame
5localSnapID = eventMan.sendSnap(
6 name="snap_name",
7 fileTag=None,
8 imgFrame=inImgFrame,
9 imgDetections=None,
10 tags=[],
11 extras={}
12)Upload Callback Arguments (Optional)
sendSnap() can invoke the optional successCallback and failureCallback arguments once the upload attempt completes. Use these if you need confirmation of the snap upload or additional information from SendSnapCallbackResult, such as its Hub ID (if successfully uploaded), payload, or upload status.Python
C++
Python
Python
1# Define the optional callback functions
2def uploadSuccessCallback(sendSnapResult):
3 print(f"Successfully uploaded Snap: {sendSnapResult.snapName} to the hub.")
4
5def uploadFailureCallback(sendSnapResult):
6 print(f"Upload of Snap: {sendSnapResult.snapName} to the hub has failed.")
7
8# Create the EventsManager instance
9eventMan = dai.EventsManager()
10
11# Send snap with ImgFrame and ImgDetections
12localSnapID = eventMan.sendSnap(
13 name="snap_name",
14 fileTag="file_tag",
15 imgFrame=inImgFrame,
16 imgDetections=inImgDetections,
17 tags=["examples", "python"],
18 extras={"confidence": "0.75", "location": "01"},
19 successCallback=uploadSuccessCallback,
20 failureCallback=uploadFailureCallback
21)Sending snaps (python)
Sending snaps (C++)
Advanced Use: Sending Snaps using FileGroups
FileGroup is created automatically from the image (and detections) when using sendSnap(). You can also create a FileGroup explicitly. When sending a FileGroup, all included files are uploaded to the Luxonis Hub together. The group's upload will either fully succeed or fail, depending on your allocated storage capacity - it must be large enough to accommodate all files in the group.The example below demonstrates the same functionality using the FileGroup object explicitly. This approach involves creating a FileGroup instance and adding files to it. Common file pairs, such as ImgFrame and ImgDetections, can be added simultaneously, or separately as individual files. More information can be found in the FileGroup class documentation.Python
C++
Python
Python
1# Create the EventsManager instance
2eventMan = dai.EventsManager()
3
4# Create the FileGroup instance
5fileGroup = dai.FileGroup()
6
7# Add files to fileGroup
8fileGroup.addImageDetectionsPair("file_tag", inImgFrame, inImgDetections)
9
10# Send snap with the fileGroup
11localSnapID = eventMan.sendSnap(
12 name="snap_name",
13 fileGroup=fileGroup,
14 tags=["examples", "python"],
15 extras={"confidence": "0.75", "location": "01"}
16)Sending snaps using a FileGroup (python)
Sending snaps using a FileGroup (C++)
Caching
Overview
sendSnap() is called and the snap cannot be delivered to the Hub after a number of retry attempts, the snap is dropped and discarded. If you want to preserve snaps during network disruptions, you can enable local caching. Once enabled, snaps that fail to upload are stored locally and can be retransmitted when connectivity is restored.Enabling Caching
setCacheIfCannotSend() method on your EventsManager instance:Python
C++
Python
Python
1# Create the EventsManager instance
2eventMan = dai.EventsManager()
3
4# Enable caching for snaps that cannot be sent
5eventMan.setCacheIfCannotSend(True)Configuring the Cache Directory
setCacheDir() method:Python
C++
Python
Python
1# Create the EventsManager instance
2eventMan = dai.EventsManager()
3
4# Enable caching
5eventMan.setCacheIfCannotSend(True)
6
7# Set a custom cache directory
8eventMan.setCacheDir("/path/to/cache/directory")Uploading Previously Cached Snaps on Application Startup
uploadCachedOnStart flag to true when constructing the EventsManager:Python
C++
Python
Python
1# Create the EventsManager instance with uploadCachedOnStart enabled
2eventMan = dai.EventsManager(uploadCachedOnStart=True)uploadCachedOnStart flag determines whether cached snaps persist across application restarts. If uploadCachedOnStart is not enabled (false or not set) and cached data exists in local storage, it will be automatically cleared when the EventsManager is initialized. To preserve cached snaps across application restarts and have them uploaded to the Hub during the next run, you must explicitly set uploadCachedOnStart to true. Otherwise, cached data will be deleted.Upload Rate Management and Upload Priority
- Your application can continue sending fresh snaps without being blocked by the backlog of cached data
- Hub rate limits (hourly file upload counts, bandwidth restrictions) are not exceeded
- Cached snaps are eventually uploaded without degrading real-time data collection
How and when are snaps uploaded to the Hub?
FileGroup instances or snaps are grouped together in a single request. Batches are sent at regular intervals (by default every 30 seconds), which may cause a brief delay before snaps appear in the Hub. For increased batch frequency, please contact support.