```bash
# List your datasets
curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://platform.ultralytics.com/api/datasets
```

Explore the full interactive API reference in the [Ultralytics Platform API docs](https://platform.ultralytics.com/api/docs).

graph LR
    A[API Key] --> B[Datasets]
    A --> C[Projects]
    A --> D[Models]
    A --> E[Deployments]
    B -->|train on| D
    C -->|contains| D
    D -->|deploy to| E
    D -->|export| F[Exports]
    B -->|auto-annotate| B

Authorization: Bearer YOUR_API_KEY

API keys use the format `ul_` followed by 40 hex characters. Keep your key secret -- never commit it to version control or share it publicly.

```bash
curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://platform.ultralytics.com/api/datasets
```

```python
import requests

headers = {"Authorization": "Bearer YOUR_API_KEY"}
response = requests.get(
    "https://platform.ultralytics.com/api/datasets",
    headers=headers,
)
data = response.json()
```

```javascript
const response = await fetch("https://platform.ultralytics.com/api/datasets", {
  headers: { Authorization: "Bearer YOUR_API_KEY" },
});
const data = await response.json();
```

https://platform.ultralytics.com/api

Retry-After: 12
X-RateLimit-Reset: 2026-02-21T12:34:56.000Z

When you receive a `429` status code, wait for `Retry-After` (or until `X-RateLimit-Reset`) before retrying. See the [rate limit FAQ](#how-do-i-handle-rate-limits) for an exponential backoff implementation.

{
    "datasets": [...],
    "total": 100
}

{
    "error": "Dataset not found"
}

GET /api/datasets

```bash
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://platform.ultralytics.com/api/datasets?limit=10"
```

```python
import requests

resp = requests.get(
    "https://platform.ultralytics.com/api/datasets",
    headers={"Authorization": f"Bearer {API_KEY}"},
    params={"limit": 10},
)
for ds in resp.json()["datasets"]:
    print(f"{ds['name']}: {ds['imageCount']} images")
```

{
    "datasets": [
        {
            "_id": "dataset_abc123",
            "name": "my-dataset",
            "slug": "my-dataset",
            "task": "detect",
            "imageCount": 1000,
            "classCount": 10,
            "classNames": ["person", "car"],
            "visibility": "private",
            "username": "johndoe",
            "starCount": 3,
            "isStarred": false,
            "sampleImages": [
                {
                    "url": "https://storage.example.com/...",
                    "width": 1920,
                    "height": 1080,
                    "labels": [{ "classId": 0, "bbox": [0.5, 0.4, 0.3, 0.6] }]
                }
            ],
            "createdAt": "2024-01-15T10:00:00Z",
            "updatedAt": "2024-01-16T08:30:00Z"
        }
    ],
    "total": 1,
    "region": "us"
}

GET /api/datasets/{datasetId}

POST /api/datasets

{
    "slug": "my-dataset",
    "name": "My Dataset",
    "task": "detect",
    "description": "A custom detection dataset",
    "visibility": "private",
    "classNames": ["person", "car"]
}

Valid `task` values: `detect`, `segment`, `classify`, `pose`, `obb`.

PATCH /api/datasets/{datasetId}

{
    "name": "Updated Name",
    "description": "New description",
    "visibility": "public"
}

DELETE /api/datasets/{datasetId}

POST /api/datasets/{datasetId}/clone

{
    "name": "cloned-dataset",
    "description": "My cloned dataset",
    "visibility": "private",
    "owner": "team-username"
}

GET /api/datasets/{datasetId}/export

{
    "downloadUrl": "https://storage.example.com/export.ndjson?signed=...",
    "cached": true
}

POST /api/datasets/{datasetId}/export

{
    "description": "Added 500 training images"
}

{
    "version": 3,
    "downloadUrl": "https://storage.example.com/v3.ndjson?signed=..."
}

PATCH /api/datasets/{datasetId}/export

{
    "version": 2,
    "description": "Fixed mislabeled classes"
}

{
    "ok": true
}

GET /api/datasets/{datasetId}/class-stats

{
    "classes": [{ "classId": 0, "count": 1500, "imageCount": 450 }],
    "imageStats": {
        "widthHistogram": [{ "bin": 640, "count": 120 }],
        "heightHistogram": [{ "bin": 480, "count": 95 }],
        "pointsHistogram": [{ "bin": 4, "count": 200 }]
    },
    "locationHeatmap": {
        "bins": [
            [5, 10],
            [8, 3]
        ],
        "maxCount": 50
    },
    "dimensionHeatmap": {
        "bins": [
            [2, 5],
            [3, 1]
        ],
        "maxCount": 12,
        "minWidth": 10,
        "maxWidth": 1920,
        "minHeight": 10,
        "maxHeight": 1080
    },
    "classNames": ["person", "car", "dog"],
    "cached": true,
    "sampled": false,
    "sampleSize": 1000
}

GET /api/datasets/{datasetId}/models

{
    "models": [
        {
            "_id": "model_abc123",
            "name": "experiment-1",
            "slug": "experiment-1",
            "status": "completed",
            "task": "detect",
            "epochs": 100,
            "bestEpoch": 87,
            "projectId": "project_xyz",
            "projectSlug": "my-project",
            "projectIconColor": "#3b82f6",
            "projectIconLetter": "M",
            "username": "johndoe",
            "startedAt": "2024-01-14T22:00:00Z",
            "completedAt": "2024-01-15T10:00:00Z",
            "createdAt": "2024-01-14T21:55:00Z",
            "metrics": {
                "mAP50": 0.85,
                "mAP50-95": 0.72,
                "precision": 0.88,
                "recall": 0.81
            }
        }
    ],
    "count": 1
}

POST /api/datasets/{datasetId}/predict

POST /api/datasets/ingest

graph LR
    A[Upload Archive] --> B[POST /api/datasets/ingest]
    B --> C[Process Archive]
    C --> D[Extract images]
    C --> E[Parse labels]
    C --> F[Generate thumbnails]
    D & E & F --> G[Dataset ready]

GET /api/datasets/{datasetId}/images

POST /api/datasets/{datasetId}/images/urls

DELETE /api/datasets/{datasetId}/images/{hash}

GET /api/datasets/{datasetId}/images/{hash}/labels

PUT /api/datasets/{datasetId}/images/{hash}/labels

{
    "labels": [
        { "classId": 0, "bbox": [0.5, 0.5, 0.2, 0.3] },
        { "classId": 1, "segments": [0.1, 0.2, 0.3, 0.2, 0.2, 0.4] }
    ]
}

Label coordinates use YOLO normalized values between 0 and 1. Bounding boxes use `[x_center, y_center, width, height]`.
Segmentation labels use `segments`, a flattened list of polygon vertices `[x1, y1, x2, y2, ...]`.

PATCH /api/datasets/{datasetId}/images/bulk

DELETE /api/datasets/{datasetId}/images/bulk

GET /api/projects

GET /api/projects/{projectId}

POST /api/projects

```bash
curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-project", "slug": "my-project", "description": "Detection experiments"}' \
  https://platform.ultralytics.com/api/projects
```

```python
resp = requests.post(
    "https://platform.ultralytics.com/api/projects",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={"name": "my-project", "slug": "my-project", "description": "Detection experiments"},
)
project_id = resp.json()["projectId"]
```

PATCH /api/projects/{projectId}

DELETE /api/projects/{projectId}

POST /api/projects/{projectId}/clone

POST /api/projects/{projectId}/icon

DELETE /api/projects/{projectId}/icon

GET /api/models

GET /api/models/completed

GET /api/models/{modelId}

POST /api/models

Model `.pt` file uploads are handled separately. Use the platform UI to drag-and-drop model files onto a project.

PATCH /api/models/{modelId}

DELETE /api/models/{modelId}

GET /api/models/{modelId}/files

POST /api/models/{modelId}/clone

{
    "targetProjectSlug": "my-project",
    "modelName": "cloned-model",
    "description": "Cloned from public model",
    "owner": "team-username"
}

POST /api/models/{modelId}/track-download

POST /api/models/{modelId}/predict

```bash
curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "[email protected]" \
  -F "conf=0.5" \
  https://platform.ultralytics.com/api/models/MODEL_ID/predict
```

```python
with open("image.jpg", "rb") as f:
    resp = requests.post(
        f"https://platform.ultralytics.com/api/models/{model_id}/predict",
        headers={"Authorization": f"Bearer {API_KEY}"},
        files={"file": f},
        data={"conf": 0.5},
    )
results = resp.json()["images"][0]["results"]
```

{
    "images": [
        {
            "shape": [1080, 1920],
            "results": [
                {
                    "class": 0,
                    "name": "person",
                    "confidence": 0.92,
                    "box": { "x1": 100, "y1": 50, "x2": 300, "y2": 400 }
                }
            ]
        }
    ],
    "metadata": {
        "imageCount": 1
    }
}

POST /api/models/{modelId}/predict/token

This route is used by the in-app Predict tab to issue short-lived inference tokens for direct browser → predict-service calls (lower latency, no API proxy). It requires an active platform browser session and is not available via API key. For programmatic inference, call [`POST /api/models/{modelId}/predict`](#run-inference) with your API key.

POST /api/models/{modelId}/predict/warmup

The warmup route is used by the Predict tab to pre-load a model's weights on the predict service before the user's first inference. It requires an active platform browser session and is not available via API key.

graph LR
    A[POST /training/start] --> B[Job Created]
    B --> C{Training}
    C -->|progress| D[GET /models/id/training]
    C -->|cancel| E[DELETE /models/id/training]
    C -->|complete| F[Model Ready]
    F --> G[Deploy or Export]

POST /api/training/start

```bash
curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "modelId": "MODEL_ID",
    "projectId": "PROJECT_ID",
    "gpuType": "rtx-4090",
    "trainArgs": {
      "model": "yolo26n.pt",
      "data": "ul://username/datasets/my-dataset",
      "epochs": 100,
      "imgsz": 640,
      "batch": 16
    }
  }' \
  https://platform.ultralytics.com/api/training/start
```

```python
resp = requests.post(
    "https://platform.ultralytics.com/api/training/start",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={
        "modelId": "MODEL_ID",
        "projectId": "PROJECT_ID",
        "gpuType": "rtx-4090",
        "trainArgs": {
            "model": "yolo26n.pt",
            "data": "ul://username/datasets/my-dataset",
            "epochs": 100,
            "imgsz": 640,
            "batch": 16,
        },
    },
)
```

Available GPU types include `rtx-4090`, `a100-80gb-pcie`, `a100-80gb-sxm`, `h100-sxm`, `rtx-pro-6000`, and others. See [Cloud Training](../train/cloud-training.md) for the full list with pricing.

GET /api/models/{modelId}/training

DELETE /api/models/{modelId}/training

Only `GET /api/deployments`, `POST /api/deployments`, `GET /api/deployments/{deploymentId}`, and `DELETE /api/deployments/{deploymentId}` support API-key authentication. The `predict`, `health`, `logs`, `metrics`, `start`, and `stop` sub-routes require an active platform browser session — they are convenience proxies for the in-app UI. For programmatic inference, call the deployment's own endpoint URL (e.g., `https://predict-abc123.run.app/predict`) directly with your API key. [Dedicated endpoints](../deploy/endpoints.md#using-endpoints) are not rate-limited.

graph LR
    A[Create] --> B[Deploying]
    B --> C[Ready]
    C -->|stop| D[Stopped]
    D -->|start| C
    C -->|delete| E[Deleted]
    D -->|delete| E
    C -->|predict| F[Inference Results]

GET /api/deployments

POST /api/deployments

{
    "modelId": "model_abc123",
    "name": "my-deployment",
    "region": "us-central1",
    "resources": {
        "cpu": 1,
        "memoryGi": 2,
        "minInstances": 0,
        "maxInstances": 1
    }
}

The deployment dialog currently submits fixed defaults of `cpu=1`, `memoryGi=2`, `minInstances=0`, and `maxInstances=1`. The API route accepts a `resources` object, but plan limits cap `minInstances` at `0` and `maxInstances` at `1`.

Choose a region close to your users for lowest latency. The platform UI shows latency estimates for all 43 available regions.

GET /api/deployments/{deploymentId}

DELETE /api/deployments/{deploymentId}

POST /api/deployments/{deploymentId}/start

POST /api/deployments/{deploymentId}/stop

GET /api/deployments/{deploymentId}/health

POST /api/deployments/{deploymentId}/predict

GET /api/deployments/{deploymentId}/metrics

GET /api/deployments/{deploymentId}/logs

`GET /api/monitoring` is a UI-only route and requires an active platform browser session. It does not accept API-key authentication. Query individual deployment metrics via the per-deployment routes (which are also browser-session only) or use [Cloud Monitoring exports](https://cloud.google.com/monitoring) on the deployed Cloud Run service for programmatic access.

GET /api/monitoring

GET /api/exports

POST /api/exports

```bash
curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"modelId": "MODEL_ID", "format": "onnx"}' \
  https://platform.ultralytics.com/api/exports
```

```python
resp = requests.post(
    "https://platform.ultralytics.com/api/exports",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={"modelId": "MODEL_ID", "format": "onnx"},
)
export_id = resp.json()["exportId"]
```

GET /api/exports/{exportId}

DELETE /api/exports/{exportId}

POST /api/exports/{exportId}/track-download

The Activity routes are powered by browser-authenticated requests from the platform UI. They are not exposed as a public API, do not accept API-key authentication, and the route shapes below are documented only for reference. Use the Activity feed in the platform UI to view, mark, or archive events.

GET /api/activity

POST /api/activity/mark-seen

{
    "all": true
}

{
    "eventIds": ["EVENT_ID_1", "EVENT_ID_2"]
}

POST /api/activity/archive

{
    "all": true,
    "archive": true
}

{
    "eventIds": ["EVENT_ID_1", "EVENT_ID_2"],
    "archive": false
}

GET /api/trash

POST /api/trash

{
    "id": "item_abc123",
    "type": "dataset"
}

DELETE /api/trash

{
    "id": "item_abc123",
    "type": "dataset"
}

Permanent deletion cannot be undone. The resource and all associated data will be removed.

DELETE /api/trash/empty

`DELETE /api/trash/empty` requires an authenticated browser session and is not available via API key. Use the **Empty Trash** button in the UI instead.

Billing amounts use cents (`creditsCents`) where `100 = $1.00`.

GET /api/billing/balance

{
    "creditsCents": 2500,
    "plan": "free",
    "cashBalance": 25,
    "creditBalance": 0,
    "reservedAmount": 0,
    "totalBalance": 25
}

GET /api/billing/usage-summary

GET /api/billing/transactions

POST /api/billing/checkout-session

{
    "amount": 25,
    "owner": "team-username"
}

POST /api/billing/subscription-checkout

{
    "planId": "pro",
    "billingCycle": "monthly",
    "owner": "team-username"
}

DELETE /api/billing/subscription-checkout

{
    "resume": true
}

GET /api/billing/auto-topup

PATCH /api/billing/auto-topup

{
    "enabled": true,
    "thresholdCents": 500,
    "amountCents": 2500
}

GET /api/billing/payment-methods

POST /api/billing/payment-methods/setup

POST /api/billing/payment-methods/default

{
    "paymentMethodId": "pm_123"
}

PATCH /api/billing/payment-methods

{
    "name": "Jane Doe",
    "address": {
        "line1": "123 Main St",
        "city": "San Francisco",
        "state": "CA",
        "postal_code": "94105",
        "country": "US"
    }
}

DELETE /api/billing/payment-methods/{id}

Storage routes require an active platform browser session and are not accessible via API key. Use the [Settings > Profile](../account/settings.md#storage-usage) page in the UI for interactive breakdowns.

GET /api/storage

{
    "tier": "free",
    "usage": {
        "storage": {
            "current": 1073741824,
            "limit": 107374182400,
            "percent": 1.0
        }
    },
    "region": "us",
    "username": "johndoe",
    "updatedAt": "2024-01-15T10:00:00Z",
    "breakdown": {
        "byCategory": {
            "datasets": { "bytes": 536870912, "count": 2 },
            "models": { "bytes": 268435456, "count": 4 },
            "exports": { "bytes": 268435456, "count": 3 }
        },
        "topItems": [
            {
                "_id": "dataset_abc123",
                "name": "my-dataset",
                "slug": "my-dataset",
                "sizeBytes": 536870912,
                "type": "dataset"
            },
            {
                "_id": "model_def456",
                "name": "experiment-1",
                "slug": "experiment-1",
                "sizeBytes": 134217728,
                "type": "model",
                "parentName": "My Project",
                "parentSlug": "my-project"
            }
        ]
    }
}

POST /api/upload/signed-url

{
    "assetType": "images",
    "assetId": "abc123",
    "filename": "my-image.jpg",
    "contentType": "image/jpeg",
    "totalBytes": 5242880
}

{
    "sessionId": "session_abc123",
    "uploadUrl": "https://storage.example.com/...",
    "objectPath": "images/abc123/my-image.jpg",
    "downloadUrl": "https://cdn.example.com/...",
    "expiresAt": "2026-02-22T12:00:00Z"
}

POST /api/upload/complete

{
    "datasetId": "abc123",
    "objectPath": "datasets/abc123/images/my-image.jpg",
    "filename": "my-image.jpg",
    "contentType": "image/jpeg",
    "size": 5242880
}

GET /api/api-keys

POST /api/api-keys

{
    "name": "training-server"
}

DELETE /api/api-keys

curl -X DELETE \
  -H "Authorization: Bearer YOUR_API_KEY" \
  "https://platform.ultralytics.com/api/api-keys?keyId=KEY_ID"

GET /api/teams

POST /api/teams/create

{
    "username": "my-team",
    "fullName": "My Team"
}

GET /api/members

POST /api/members

{
    "email": "[email protected]",
    "role": "editor"
}

| Role     | Permissions                                                                    |
| -------- | ------------------------------------------------------------------------------ |
| `viewer` | Read-only access to workspace resources                                        |
| `editor` | Create, edit, and delete resources                                             |
| `admin`  | Manage members, billing, and all resources (only assignable by the team owner) |

The team `owner` is the creator and cannot be invited. Owner is transferred separately via [`POST /api/members/transfer-ownership`](#transfer-ownership). See [Teams](../account/teams.md) for full role details.

PATCH /api/members/{userId}

DELETE /api/members/{userId}

POST /api/members/transfer-ownership

POST /api/invites/accept

GET /api/invites/info

DELETE /api/invites/{inviteId}

POST /api/invites/{inviteId}/resend

GET /api/explore/search

GET /api/explore/sidebar

GET /api/users

PATCH /api/users

{
    "username": "target-user",
    "followed": true
}

GET /api/username/check

GET /api/settings
POST /api/settings

POST /api/settings/icon
DELETE /api/settings/icon

POST /api/onboarding

GET /api/gdpr

POST /api/gdpr

{
    "action": "export"
}

{
    "action": "delete",
    "confirmationWord": "DELETE"
}

{
    "action": "delete",
    "confirmationWord": "DELETE",
    "teamUsername": "my-team"
}

Account deletion is permanent and cannot be undone. All data, models, and deployments will be deleted.

pip install ultralytics

yolo check

Platform integration requires **ultralytics>=8.4.35**. Lower versions will NOT work with Platform.

```bash
yolo settings api_key=YOUR_API_KEY
```

```bash
export ULTRALYTICS_API_KEY=YOUR_API_KEY
```

```python
from ultralytics import settings

settings.api_key = "YOUR_API_KEY"
```

from ultralytics import YOLO

model = YOLO("yolo26n.pt")

# Train on your Platform dataset
model.train(
    data="ul://your-username/datasets/your-dataset",
    epochs=100,
    imgsz=640,
)

from ultralytics import YOLO

model = YOLO("yolo26n.pt")

# Results automatically sync to Platform
model.train(
    data="coco8.yaml",
    epochs=100,
    project="your-username/my-project",
    name="experiment-1",
)

# Your own model
model = YOLO("ul://username/project/model-name")

# Official model
model = YOLO("ul://ultralytics/yolo26/yolo26n")

results = model("image.jpg")

# Access results
for r in results:
    boxes = r.boxes  # Detection boxes
    masks = r.masks  # Segmentation masks
    keypoints = r.keypoints  # Pose keypoints
    probs = r.probs  # Classification probabilities

# Export to ONNX
model.export(format="onnx", imgsz=640, half=True)

# Export to TensorRT
model.export(format="engine", imgsz=640, half=True)

# Export to CoreML
model.export(format="coreml", imgsz=640)

metrics = model.val(data="ul://username/datasets/my-dataset")

print(f"mAP50: {metrics.box.map50}")
print(f"mAP50-95: {metrics.box.map}")

**All plans**: Training progress via the `ultralytics` SDK (real-time metrics, completion notifications) works automatically on every plan — just set `project=username/my-project name=my-run` when training and the SDK streams events back to the Platform. No user-side webhook registration is required.

**User-facing webhook subscriptions** (POST callbacks to a URL you control) are on the Enterprise roadmap and not currently available. In the meantime, poll `GET /api/models/{modelId}/training` for status or use the [activity feed](#activity-api) in the UI.

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://platform.ultralytics.com/api/datasets?limit=50"

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://platform.ultralytics.com/api/activity?page=2&limit=20"

curl "https://platform.ultralytics.com/api/explore/search?type=datasets&offset=20&sort=stars"

import time

import requests


def api_request_with_retry(url, headers, max_retries=3):
    for attempt in range(max_retries):
        response = requests.get(url, headers=headers)
        if response.status_code != 429:
            return response
        wait = int(response.headers.get("Retry-After", 2**attempt))
        time.sleep(wait)
    raise Exception("Rate limit exceeded")

https://platform.ultralytics.com/username/project/model-name
                                  ^^^^^^^^ ^^^^^^^ ^^^^^^^^^^
                                  username project   model