Working with Snaps

This guide walks you through managing Snaps programmatically using Luxonis Hub GraphQL API. You'll learn how to list snaps, retrieve detailed information, and delete them.

Creating Snaps

To send or create Snaps from your applications, you must use the DepthAI. Check out the Snaps in DepthAI documentation for details on how to emit Snaps from your applications.This guide focuses on querying, filtering, and managing existing Snaps via GraphQL API.

Prerequisites

Before starting, you should be familiar with GraphQL basics. If you're new to GraphQL, check out About GraphQL.You'll also need an API key to authenticate your requests.

To interact with Luxonis Hub API, you need an API key. API keys provide full access to your team's resources.Follow API Keys documentation to create a key in the Luxonis Hub web UI.Once you have your API key, include it in the Authorization header:

Command Line

1Authorization: Bearer <your_api_key>

Use the snaps query to retrieve a list of all snaps in your team. This query supports cursor-based pagination for efficient navigation through large datasets.

Basic List Query

Graphql

1query {
2  team {
3    snaps(first: 10) {
4      nodes {
5        id
6        name
7        createdAt
8        tags
9        extras
10        files {
11          id
12          name
13          classification
14        }
15        sourceDeviceId
16        sourceAppIdentifier
17      }
18      pageInfo {
19        hasNextPage
20        endCursor
21      }
22    }
23  }
24}

Query breakdown:

first: 10 - limits results to 10 snaps
nodes - array of snap objects
pageInfo - pagination metadata (cursor for next page)

Snap fields explained:

id: Unique snap identifier
name: Snap name (e.g., "car_detected", "data_collection")
createdAt: Timestamp when snap was created
tags: Array of tags for grouping (e.g., "night", "dataset_v2")
extras: JSON object with custom key-value pairs for searchable metadata
files: Array of attached files (images, videos, point clouds, etc.)
sourceDeviceId: Device ID that created the snap
sourceAppIdentifier: App that created the snap

To fetch the next page, use the endCursor from the previous response:

Graphql

1query($after: String) {
2  team {
3    snaps(first: 10, after: $after) {
4      nodes {
5        id
6        name
7        createdAt
8      }
9      pageInfo {
10        hasNextPage
11        endCursor
12      }
13    }
14  }
15}

Variables:

JSON

1{
2  "after": "cursor_from_previous_response"
3}

Filtering Snaps

Filter snaps by various criteria to find specific data:Filter by time range:

Graphql

1query($from: DateTime!, $to: DateTime!) {
2  team {
3    snaps(
4      first: 10,
5      filter: {
6        createdFrom: $from,
7        createdTo: $to
8      }
9    ) {
10      nodes {
11        id
12        name
13        createdAt
14      }
15    }
16  }
17}

Variables:

JSON

1{
2  "from": "2024-01-01T00:00:00Z",
3  "to": "2024-02-01T00:00:00Z"
4}

Filter by device:

Graphql

1query {
2  team {
3    snaps(
4      first: 10,
5      filter: { deviceId: "device-id" }
6    ) {
7      nodes {
8        id
9        name
10        sourceDeviceId
11      }
12    }
13  }
14}

Filter by app identifier:

Graphql

1query {
2  team {
3    snaps(
4      first: 10,
5      filter: { deviceAppIdentifier: "my-app" }
6    ) {
7      nodes {
8        id
9        name
10        sourceAppIdentifier
11      }
12    }
13  }
14}

Filter by name:

Graphql

1query {
2  team {
3    snaps(
4      first: 10,
5      filter: { name: "car_detected" }
6    ) {
7      nodes {
8        id
9        name
10      }
11    }
12  }
13}

Filter by tags:

Graphql

1query {
2  team {
3    snaps(
4      first: 10,
5      filter: { tags: ["night", "validation"] }
6    ) {
7      nodes {
8        id
9        name
10        tags
11      }
12    }
13  }
14}

Filter by extras (custom metadata):

Graphql

1query {
2  team {
3    snaps(
4      first: 10,
5      filter: { extras: { scene: "warehouse", lighting: "low" } }
6    ) {
7      nodes {
8        id
9        name
10        extras
11      }
12    }
13  }
14}

Filter by file classification:

Graphql

1query {
2  team {
3    snaps(
4      first: 10,
5      filter: { withFilesClassifiedAs: [IMAGE_COLOR, VIDEO] }
6    ) {
7      nodes {
8        id
9        name
10        files {
11          classification
12        }
13      }
14    }
15  }
16}

Available file classifications:

IMAGE_COLOR: Color images
IMAGE_STEREO_LEFT: Left stereo image
IMAGE_STEREO_RIGHT: Right stereo image
VIDEO: Video files
POINTCLOUD: Point cloud data
ANNOTATION: Annotation files
DISPARITY: Disparity maps
UNKNOWN_FILE: Other file types

Combine multiple filters:

Graphql

1query {
2  team {
3    snaps(
4      first: 10,
5      filter: {
6        deviceId: "device-id",
7        tags: ["validation"],
8        createdFrom: "2024-01-01T00:00:00Z"
9      }
10    ) {
11      nodes {
12        id
13        name
14        tags
15        createdAt
16      }
17    }
18  }
19}

Retrieve detailed information about a specific snap using its ID, including file download URLs.

Graphql

1query($snapId: ID!) {
2  team {
3    snap(snapId: $snapId) {
4      id
5      name
6      createdAt
7      tags
8      extras
9      files {
10        id
11        name
12        hash
13        mimeType
14        size
15        presignedUrl
16        classification
17      }
18      sourceDeviceId
19      sourceSerialNumber
20      sourceAppIdentifier
21    }
22  }
23}

Variables:

JSON

1{
2  "snapId": "snap-id-from-list"
3}

Response example:

JSON

1{
2  "data": {
3    "team": {
4      "snap": {
5        "id": "snap-abc123",
6        "name": "car_detected",
7        "createdAt": "2024-01-15T10:30:00Z",
8        "tags": ["validation", "warehouse"],
9        "extras": { "scene": "warehouse", "lighting": "low" },
10        "files": [
11          {
12            "id": "file-xyz789",
13            "name": "image.jpg",
14            "hash": "abc123...",
15            "mimeType": "image/jpeg",
16            "size": 524288,
17            "presignedUrl": "https://storage.example.com/snap-abc123/image.jpg?signature=...",
18            "classification": "IMAGE_COLOR"
19          }
20        ],
21        "sourceDeviceId": "device-123",
22        "sourceSerialNumber": "OAK123456",
23        "sourceAppIdentifier": "detection-app"
24      }
25    }
26  }
27}

Key fields explained:

presignedUrl: Direct, time-limited URL to download the file. Use this URL to download files without authentication.
hash: File checksum for integrity verification
mimeType: MIME type of the file (e.g., "image/jpeg", "video/mp4")
size: File size in bytes
sourceSerialNumber: Device serial number that created the snap
sourceAppIdentifier: Application identifier that emitted the snap

Delete snaps using either their IDs or by applying filters. Deletion happens asynchronously as a background task.

Asynchronous Deletion

Snap deletion is not immediate. The API returns a bgTaskId that you can use to track deletion progress.

Method 1: Delete by IDs

Delete specific snaps using their IDs:

Graphql

1mutation DeleteSnapsByIds($ids: [ID!]!) {
2  team {
3    deleteSnapsByIds(ids: $ids) {
4      status
5      bgTaskId
6    }
7  }
8}

Variables:

JSON

1{
2  "ids": ["snap-id-1", "snap-id-2", "snap-id-3"]
3}

Response:

JSON

1{
2  "data": {
3    "team": {
4      "deleteSnapsByIds": {
5        "status": "SUCCESS",
6        "bgTaskId": "bg-task-abc123"
7      }
8    }
9  }
10}

Method 2: Delete by Filter

Delete snaps matching specific criteria:

Graphql

1mutation DeleteSnapsByFilter {
2  team {
3    deleteSnapsByFilter(
4      filter: {
5        deviceId: "device-id",
6        createdFrom: "2024-01-01T00:00:00Z",
7        createdTo: "2024-02-01T00:00:00Z",
8        tags: ["test"]
9      }
10    ) {
11      status
12      bgTaskId
13    }
14  }
15}

Available deletion filters:

deviceId: Delete snaps from a specific device
deviceAppId: Delete snaps from a specific app instance
deviceAppIdentifier: Delete snaps from apps with this identifier
createdFrom: Delete snaps created after this timestamp
createdTo: Delete snaps created before this timestamp
name: Delete snaps with this name
tags: Delete snaps with these tags
extras: Delete snaps with these custom metadata
withFilesClassifiedAs: Delete snaps containing files of this classification

Check Deletion Status

Track deletion progress using the bgTaskId:

Graphql

1query($bgTaskId: ID!) {
2  team {
3    bgTask(bgTaskId: $bgTaskId) {
4      id
5      state {
6        deletedCount
7        totalCount
8      }
9      createdAt
10      completedAt
11      failedAt
12    }
13  }
14}

Variables:

JSON

1{
2  "bgTaskId": "bg-task-id-from-deletion"
3}

Response (in progress):

JSON

1{
2  "data": {
3    "team": {
4      "bgTask": {
5        "id": "bg-task-abc123",
6        "state": {
7          "deletedCount": 150,
8          "totalCount": 500
9        },
10        "createdAt": "2024-01-15T11:00:00Z",
11        "completedAt": null,
12        "failedAt": null
13      }
14    }
15  }
16}

Response (completed):

JSON

1{
2  "data": {
3    "team": {
4      "bgTask": {
5        "id": "bg-task-abc123",
6        "state": {
7          "deletedCount": 500,
8          "totalCount": 500
9        },
10        "createdAt": "2024-01-15T11:00:00Z",
11        "completedAt": "2024-01-15T11:05:30Z",
12        "failedAt": null
13      }
14    }
15  }
16}

Status Values

The status field in deletion response can be:

SUCCESS: Deletion task created successfully
IDS_NOT_FROM_TEAM: One or more snap IDs don't belong to your team
BG_TASK_LIMIT_REACHED: Too many background tasks running, try again later

Summary

In this guide, you learned how to:

List snaps with pagination and filtering
Retrieve detailed information about individual snaps
Download snap files using presigned URLs
Delete snaps by IDs or using filters
Track deletion progress via background tasks

Key Takeaways

Use tags and extras for effective snap organization and searching
Leverage filters to query specific subsets of your data
Deletion is async - always check bgTaskId for progress
Presigned URLs are time-limited - download files promptly

Next Steps

Check out Snaps feature documentation to learn about managing snaps via the Luxonis Hub UI
Learn how to send snaps from your applications using DepthAI
Explore the full schema reference for all snap-related types and mutations
Discover more automation guides for additional API integration examples

ON THIS PAGE

Working with Snaps

Prerequisites

Step 1: Obtain API Key

Step 2: List Snaps

Basic List Query

Filtering Snaps

Step 3: Load Individual Snap

Step 4: Delete Snaps

Method 1: Delete by IDs

Method 2: Delete by Filter

Check Deletion Status

Status Values

Summary

Next Steps

ON THIS PAGE

Working with Snaps

Prerequisites

Step 1: Obtain API Key

Step 2: List Snaps

Basic List Query

Pagination

Filtering Snaps

Step 3: Load Individual Snap

Step 4: Delete Snaps

Method 1: Delete by IDs

Method 2: Delete by Filter

Check Deletion Status

Status Values

Summary

Next Steps