Skip to main content

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

FieldDescription
idThe dataset UUID.
display_nameThe human-readable dataset name.
status_newThe current dataset status. Use this field for all workflow logic.
progressProcessing progress percentage (0–100).
n_imagesTotal number of images in the dataset.
n_videosTotal number of videos in the dataset.
n_objectsTotal number of detected objects (if object detection enrichment was applied).
fatal_error_msgError message if processing failed; otherwise null.

​
Dataset Status Values

status_newDescription
DRAFTDataset is being set up. Files may be uploading but processing has not started.
INDEXINGDataset is being indexed for search and retrieval.
READ ONLYDataset is being updated — add media, enrichment, or reindex in progress. Browsing still works.
PARTIAL INDEXNew media was added but the dataset has not yet been re-clustered. Trigger a reindex to reach READY.
READYDataset is fully processed and available for search, enrichment, and export.
ERRORProcessing 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 CodeMeaning
200Dataset metadata returned successfully.
401Unauthorized — check your JWT token.
404Dataset 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.