Visual Layer Documentation: Visual Intelligence, At Scale

How This Helps

Poll this endpoint to determine when a dataset is ready for search, enrichment, or export operations. Both the dataset metadata and the current processing status are returned in a single call.

The status field is being retired. Use status_new for all status checks and workflow logic. In a future update, status_new will be renamed to status.

Prerequisites

A valid JWT token. See Authentication.
A dataset ID (visible in the browser URL: https://app.visual-layer.com/dataset/<dataset_id>/data).

Get Dataset Status

Retrieve current status and metadata for a dataset.

GET /api/v1/dataset/{dataset_id}
Authorization: Bearer <jwt>

Example

curl -H "Authorization: Bearer <jwt>" \
  "https://app.visual-layer.com/api/v1/dataset/<dataset_id>"

Response

{
  "id": "ad48d250-1232-11f1-bfca-fa39f6ed1f22",
  "display_name": "My Dataset",
  "description": "",
  "source_type": "BUCKET",
  "owned_by": "VL",
  "created_at": "2025-04-24T07:44:46.136915",
  "status_new": "READY",
  "progress": 100,
  "n_images": 26,
  "n_videos": 0,
  "n_objects": 0,
  "fatal_error_msg": null,
  "source_dataset_id": null
}

Key Response Fields

Field	Description
`id`	The dataset UUID.
`display_name`	The human-readable dataset name.
`status_new`	The current dataset status. Use this field for all workflow logic.
`progress`	Processing progress percentage (0–100).
`n_images`	Total number of images in the dataset.
`n_videos`	Total number of videos in the dataset.
`n_objects`	Total number of detected objects (if object detection enrichment was applied).
`fatal_error_msg`	Error message if processing failed; otherwise `null`.

Dataset Status Values

`status_new`	Description
`DRAFT`	Dataset is being set up. Files may be uploading but processing has not started.
`INDEXING`	Dataset is being indexed for search and retrieval.
`READ ONLY`	Dataset is being updated — add media, enrichment, or reindex in progress. Browsing still works.
`PARTIAL INDEX`	New media was added but the dataset has not yet been re-clustered. Trigger a reindex to reach `READY`.
`READY`	Dataset is fully processed and available for search, enrichment, and export.
`ERROR`	Processing failed. Check `fatal_error_msg` for details.

Use status_new == "READY" as your condition before starting enrichment, search, or export operations. status_new == "PARTIAL INDEX" is safe for browsing but the dataset has not yet been re-clustered.

Get Dataset Creation Status

For datasets created via the ingestion workflow (local file uploads), use this endpoint to track creation progress:

GET /api/v1/datasets/{dataset_id}/creation-status
Authorization: Bearer <jwt>

Example

curl -H "Authorization: Bearer <jwt>" \
  "https://app.visual-layer.com/api/v1/datasets/<dataset_id>/creation-status"

Response

{
  "status": "READY",
  "progress": 100
}

Python Polling Example

The following example polls until a dataset reaches READY status.

import requests
import time

VL_BASE_URL = "https://app.visual-layer.com"
JWT_TOKEN = "<your-jwt-token>"
DATASET_ID = "<your-dataset-id>"

headers = {"Authorization": f"Bearer {JWT_TOKEN}"}

while True:
    resp = requests.get(
        f"{VL_BASE_URL}/api/v1/dataset/{DATASET_ID}",
        headers=headers,
    )
    resp.raise_for_status()
    data = resp.json()
    status = data.get("status_new")
    progress = data.get("progress", 0)
    print(f"  Status: {status} ({progress}%)")
    if status in ("READY", "PARTIAL INDEX", "ERROR"):
        break
    time.sleep(15)

print(f"Final status: {status}")

Response Codes

See Error Handling for the error response format and Python handling patterns.

HTTP Code	Meaning
200	Dataset metadata returned successfully.
401	Unauthorized — check your JWT token.
404	Dataset not found, or the authenticated user does not have access to it.

Add Media to an Existing Dataset

Add new images or videos and monitor the resulting status transitions.

Authentication

Generate the JWT token required for all API calls.

API Getting Started

Create a Dataset

Manage Datasets

Search

Guides

Self-Hosted Administration

Useful Scripts

Retrieve Dataset Status

How This Helps

Prerequisites

Get Dataset Status

Example

Response

Key Response Fields

Dataset Status Values

Get Dataset Creation Status

Example

Response

Python Polling Example

Response Codes

Add Media to an Existing Dataset

Authentication

How This Helps

​Prerequisites

​Get Dataset Status

​Example

​Response

​Key Response Fields

​Dataset Status Values

​Get Dataset Creation Status

​Example

​Response

​Python Polling Example

​Response Codes

​Related Resources

Add Media to an Existing Dataset

Authentication

Prerequisites

Get Dataset Status

Example

Response

Key Response Fields

Dataset Status Values

Get Dataset Creation Status

Example

Response

Python Polling Example

Response Codes

Related Resources