Skip to main content

​
Quickstart

Get your first synthetic dataset validated in under 5 minutes. This guide walks you through uploading a dataset, running a full validation, and retrieving your scores.
You will need an API key to follow this guide. If you do not have one yet, sign up at validate.lucitra.ai and generate a key from the dashboard.
1
Get your API key
2
Log in to validate.lucitra.ai and navigate to Settings > API Keys. Click Create Key and copy the value. API keys start with the luci_ prefix.
3
Store your API key securely. It will only be displayed once. If you lose it, revoke the old key and generate a new one.
4
Set your key as an environment variable for the rest of this guide:
5
bash
export LUCITRA_API_KEY="luci_your_api_key"
python
import os

api_key = os.environ.get("LUCITRA_API_KEY", "luci_your_api_key")
headers = {
    "Authorization": f"Bearer {api_key}",
    "Content-Type": "application/json",
}
6
Upload a dataset
7
Create a dataset record and get a signed upload URL. Supported formats are coco, kitti, nuscenes, and custom.
8
curl
curl -X POST https://api.lucitra.io/v1/datasets \
  -H "Authorization: Bearer $LUCITRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "proj_abc123",
    "name": "warehouse-pick-v2",
    "format": "coco"
  }'
python
import requests

response = requests.post(
    "https://api.lucitra.io/v1/datasets",
    headers=headers,
    json={
        "project_id": "proj_abc123",
        "name": "warehouse-pick-v2",
        "format": "coco",
    },
)
data = response.json()
dataset_id = data["id"]
upload_url = data["upload_url"]

print(f"Dataset ID: {dataset_id}")
print(f"Upload URL: {upload_url}")
9
The response includes a dataset_id and a signed upload_url. Upload your dataset archive to the signed URL:
10
curl
curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: application/zip" \
  --data-binary @warehouse-pick-v2.zip
python
with open("warehouse-pick-v2.zip", "rb") as f:
    upload_response = requests.put(
        upload_url,
        headers={"Content-Type": "application/zip"},
        data=f,
    )

print(f"Upload status: {upload_response.status_code}")
11
Datasets can be .zip or .tar.gz archives. The archive should contain your annotation files and an optional metadata.json at the root.
12
Run validation
13
Start a full validation across all four dimensions: coverage, physics plausibility, distribution quality, and sim-to-real gap.
14
curl
curl -X POST https://api.lucitra.io/v1/validate/full \
  -H "Authorization: Bearer $LUCITRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "dataset_id": "ds_abc123"
  }'
python
validation = requests.post(
    "https://api.lucitra.io/v1/validate/full",
    headers=headers,
    json={
        "dataset_id": dataset_id,
    },
)
run = validation.json()
run_id = run["run_id"]

print(f"Validation started: {run_id}")
15
The response returns a run_id that you will use to check progress and retrieve results.
16
Poll for completion
17
Validation runs asynchronously. Poll the status endpoint until status is completed.
18
curl
curl https://api.lucitra.io/v1/validate/$RUN_ID/status \
  -H "Authorization: Bearer $LUCITRA_API_KEY"
python
import time

while True:
    status_response = requests.get(
        f"https://api.lucitra.io/v1/validate/{run_id}/status",
        headers=headers,
    )
    status = status_response.json()

    print(f"Status: {status['status']}")

    if status["status"] == "completed":
        report_id = status["report_id"]
        break
    elif status["status"] == "failed":
        print(f"Error: {status['error']}")
        break

    time.sleep(2)
19
Validation typically completes in 30 to 90 seconds depending on dataset size. The status endpoint returns queued, running, completed, or failed.
20
Get your report
21
Once validation completes, retrieve the full report with scores and detailed analysis.
22
curl
curl https://api.lucitra.io/v1/reports/$REPORT_ID \
  -H "Authorization: Bearer $LUCITRA_API_KEY"
python
report = requests.get(
    f"https://api.lucitra.io/v1/reports/{report_id}",
    headers=headers,
)
result = report.json()

print(f"Overall Score: {result['scores']['overall']}/100")
print(f"Coverage: {result['scores']['coverage']}/100")
print(f"Physics: {result['scores']['physics_plausibility']}/100")
print(f"Distribution: {result['scores']['distribution_quality']}/100")
print(f"Sim-to-Real: {result['scores']['sim_to_real_gap']}/100")
23
The report includes:
24
  • Scores — 0 to 100 for each dimension and an overall composite score
  • Findings — specific issues detected, ranked by severity
  • Recommendations — actionable steps to improve data quality

    • ​
    Next Steps

    Authentication

    Understand API keys, rate limits, and enterprise tiers.

    Validation Guide

    Configure thresholds, custom rules, and dimension weights.

    CLI

    Run validations from your terminal or CI/CD pipeline.