REST API Reference#

Ultralytics Platform provides a comprehensive REST API for programmatic access to datasets, models, training, and deployments.

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

API Overview#

The API is organized around the core platform resources:

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

    classDef start fill:#4CAF50,color:#fff
    classDef proc fill:#2196F3,color:#fff

Authentication#

Resource APIs use API-key authentication, including dataset class and split management, cloning, training, exports, deployments, and supported account reads. Public endpoints support anonymous access where noted. Browser-only application routes are excluded.

Get API Key#

1. Go to Settings > API Keys
2. Click Create Key
3. Copy the generated key

See API Keys for detailed instructions.

Authorization Header#

Include your API key in all requests:

Authorization: Bearer YOUR_API_KEY

Example#

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

Base URL#

All API endpoints use:

https://platform.ultralytics.com/api

Rate Limits#

The API enforces sliding-window, Upstash Redis-backed limits per API key. Each route uses the matching category below.

When throttled, the API returns 429 with retry metadata:

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

Per API Key Limits#

Rate limits are applied automatically based on the endpoint being called. Expensive operations have tighter limits to prevent abuse, while standard CRUD operations share a generous default:

Each category has an independent counter per API key. For example, making 20 predict requests does not affect your 100 request/min default allowance.

Dedicated Endpoints (Unlimited)#

Dedicated endpoints are not subject to Platform API-key rate limits when you call the endpoint URL directly (for example, https://predict-abc123.run.app/predict). Throughput then depends on the deployed service configuration.

Response Format#

Success Responses#

Responses return JSON with resource-specific fields:

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

Error Responses#

{
    "error": "Dataset not found"
}

Datasets API#

Create, browse, and manage labeled image datasets for training YOLO models. See Datasets documentation.

List Datasets#

GET /api/datasets

Query Parameters:

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

Response:

{
    "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 Dataset#

GET /api/datasets/{datasetId}

Returns full dataset details including metadata, class names, and split counts.

Pass username when {datasetId} is a dataset slug rather than an ID.

Create Dataset#

POST /api/datasets

Body:

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

Response:

{
    "datasetId": "dataset_abc123",
    "slug": "my-dataset",
    "region": "us"
}

Update Dataset#

PATCH /api/datasets/{datasetId}

Body (partial update):

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

Dataset Icon#

POST /api/datasets/{datasetId}/icon
DELETE /api/datasets/{datasetId}/icon

Upload a WebP icon up to 5 MB as multipart form field image, or remove the current icon.

Delete Dataset#

DELETE /api/datasets/{datasetId}

Soft-deletes the dataset (moved to trash, recoverable for 30 days).

Clone Dataset#

POST /api/datasets/{datasetId}/clone

Creates a copy of a public, owned, or editable workspace dataset with all images and labels.

Optional body (all fields are optional):

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

Export Dataset#

GET /api/datasets/{datasetId}/export

Returns a JSON response with a signed download URL for the latest dataset export.

Query Parameters:

Response:

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

Create Dataset Version#

POST /api/datasets/{datasetId}/export

Create a new numbered version snapshot of the dataset. This requires Editor access or higher. The version captures current image count, class count, annotation count, and split distribution, then generates and stores an immutable NDJSON export.

Request Body:

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

All fields are optional. The description field is a user-provided label for the version.

Response:

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

Update Version Description#

PATCH /api/datasets/{datasetId}/export

Update the description of an existing version. This requires Editor access or higher.

Request Body:

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

Response:

{
    "ok": true
}

Restore Dataset Version#

POST /api/datasets/{datasetId}/restore

Rebuild the dataset's images, annotations, and classes from a saved version without copying image bytes.

{
    "version": 2
}

Get Class Statistics#

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

Returns class distribution, location heatmap, and dimension statistics. Results are cached for up to 5 minutes.

Response:

{
    "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
}

Manage Classes#

Merge classes (reassign annotations from source classes to a target, then remove the sources):

POST /api/datasets/{datasetId}/classes/merge

{
    "sourceClassIds": [2, 4],
    "targetClassId": 1
}

Class IDs are positional, so merging is not idempotent. Re-fetch the dataset before retrying.

Delete classes:

POST /api/datasets/{datasetId}/classes/delete

{
    "classIds": [2, 4]
}

Redistribute Splits#

POST /api/datasets/{datasetId}/splits/redistribute

Randomly reassign images across train, validation, and test splits. Percentages must total 100.

{
    "train": 80,
    "val": 20,
    "test": 0
}

Dataset Embeddings#

GET /api/datasets/{datasetId}/embeddings
POST /api/datasets/{datasetId}/embeddings
DELETE /api/datasets/{datasetId}/embeddings

GET returns the current UMAP analysis summary and active job status; POST enqueues an embeddings analysis job; DELETE cancels the active job.

Image Clustering#

GET /api/datasets/{datasetId}/images/clustering

Returns the UMAP 2D layout and per-image metadata for the clustering scatter view (paged and rate-limited).

Get Models Trained on Dataset#

GET /api/datasets/{datasetId}/models

Returns models that were trained using this dataset.

Response:

{
    "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
}

Auto-Annotate Dataset#

POST /api/datasets/{datasetId}/predict

Run YOLO inference on dataset images to auto-generate annotations. Uses a selected model to predict labels for unannotated images.

Body:

Dataset Ingest#

POST /api/datasets/ingest

Create a dataset ingest job for an existing dataset. The target dataset is always passed as datasetId in the JSON body, not in the URL path.

The request body requires datasetId plus exactly one of sessionId (an uploaded archive's upload session) or sourceUrl (a remote ZIP, TAR, TAR.GZ, TGZ, or NDJSON URL). Add optional targetSplit (train, val, or test) to override the archive's split structure.

For uploaded archives, the upload session is already bound to the dataset by the assetId passed to POST /api/upload/signed-url; ingest validates that assetId matches the body datasetId. Optional classMapping entries map each incoming class name to an existing zero-based class index, a class name to reuse or create, or null to skip the class. For remote sourceUrl imports, create the dataset first, then pass its datasetId to ingest.

Body (uploaded archive):

{
    "datasetId": "dataset_abc123",
    "sessionId": "session_abc123",
    "targetSplit": "train"
}

Body (remote archive or NDJSON):

{
    "datasetId": "dataset_abc123",
    "sourceUrl": "https://example.com/my-dataset.zip"
}

Body (later ingest, importing labels):

{
    "datasetId": "dataset_abc123",
    "sessionId": "session_abc123",
    "classMapping": { "person": 0, "automobile": "car", "background": null }
}

Response:

{
    "jobId": "job_abc123",
    "datasetId": "dataset_abc123",
    "status": "queued"
}

graph LR
    A[POST /api/datasets]:::start --> B[POST /api/upload/signed-url]:::proc
    B --> C[Upload archive to signed URL]:::proc
    C --> D[POST /api/upload/complete]:::proc
    D --> E[POST /api/datasets/ingest]:::proc
    E --> F[Process archive]:::proc
    F --> G[Dataset ready]:::out

    classDef start fill:#4CAF50,color:#fff
    classDef proc fill:#2196F3,color:#fff
    classDef out fill:#9C27B0,color:#fff

Dataset Images#

List Images#

GET /api/datasets/{datasetId}/images

Query Parameters:

Get Selected Images#

POST /api/datasets/{datasetId}/images

Returns the same image shape for up to 1,000 supplied image IDs. It accepts the same URL and label query controls as the list operation.

{
    "imageIds": ["IMAGE_OBJECT_ID"]
}

Get Signed Image URLs#

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

Get signed URLs for a batch of image hashes (for display in the browser).

Delete Image#

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

Get Image Labels#

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

Returns annotations and class names for a specific image.

Update Image Labels#

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

Body:

{
    "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] }
    ]
}

Bulk Image Operations#

Move images between splits (train/val/test) within a dataset:

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

Bulk delete images:

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

Projects API#

Organize your models into projects. Each model belongs to one project. See Projects documentation.

List Projects#

GET /api/projects

Query Parameters:

Get Project#

GET /api/projects/{projectId}

Create Project#

POST /api/projects

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

Update Project#

PATCH /api/projects/{projectId}

Delete Project#

DELETE /api/projects/{projectId}

Soft-deletes the project (moved to trash).

Clone Project#

POST /api/projects/{projectId}/clone

Clones a public, owned, or editable workspace project and its models into your account or workspace. An optional JSON body accepts name, slug, description, visibility, license, and destination owner overrides.

Project Icon#

POST /api/projects/{projectId}/icon
DELETE /api/projects/{projectId}/icon

Upload a WebP icon up to 5 MB as multipart form field image, or remove the current icon.

Models API#

Manage trained YOLO models — view metrics, download weights, run inference, and export to other formats. See Models documentation.

List Models#

GET /api/models

Query Parameters:

List Completed Models#

GET /api/models/completed

Returns up to 1,000 models with usable weights across all projects for training and deployment. Pass owner for a workspace.

Get Model#

GET /api/models/{modelId}

Create Model#

POST /api/models

JSON Body:

Update Model#

PATCH /api/models/{modelId}

Delete Model#

DELETE /api/models/{modelId}

Download Model Files#

GET /api/models/{modelId}/files

Returns signed download URLs for model files.

Clone Model#

POST /api/models/{modelId}/clone

Clone a public, owned, or editable workspace model to one of your projects.

Body:

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

Track Download#

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

Track model download analytics.

Run Inference#

POST /api/models/{modelId}/predict

Public models can be predicted without authentication. Private and shared models require an API key with access to the parent project.

Multipart Form:

Provide either file or source. Maximum upload size is 100 MB.

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@image.jpg" \
  -F "conf=0.5" \
  https://platform.ultralytics.com/api/models/MODEL_ID/predict

Response:

Responses contain per-image shape, speed, results, and optional dense pixel-map data (a semantic class map, or a depth map where depth = pixel × max / divisor — divisor 255 for the default 8-bit map, 65535 with bits=12|16), plus metadata with image count, function timing, task, and service versions. Internal model paths are never returned.

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

Training API#

Launch YOLO training on cloud GPUs (26 GPU types from RTX 2000 Ada to B300) and monitor progress in real time. See Cloud Training documentation.

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

    classDef start fill:#4CAF50,color:#fff
    classDef proc fill:#2196F3,color:#fff
    classDef decide fill:#FF9800,color:#fff
    classDef out fill:#9C27B0,color:#fff
    classDef error fill:#F44336,color:#fff

Start Training#

POST /api/training/start

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

Get GPU Availability#

GET /api/training/gpu-availability

Returns current GPU stock status (High, Medium, Low, or null) keyed by GPU type ID. Public, no authentication required; cached for 5 minutes.

Get Training Status#

GET /api/models/{modelId}/training

Returns the current training job status, metrics, progress, timing, GPU details, and errors. Public projects are accessible without authentication; private and shared projects require an API key with access.

Cancel Training#

DELETE /api/models/{modelId}/training

Terminates the running compute instance and marks the job as cancelled.

Deployments API#

Deploy models to dedicated inference endpoints with health checks and monitoring. New deployments use scale-to-zero by default, and the API accepts an optional resources object. See Endpoints documentation.

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

    classDef start fill:#4CAF50,color:#fff
    classDef proc fill:#2196F3,color:#fff
    classDef out fill:#9C27B0,color:#fff
    classDef error fill:#F44336,color:#fff
    classDef extern fill:#607D8B,color:#fff

List Deployments#

GET /api/deployments

Query Parameters:

Create Deployment#

POST /api/deployments

Body:

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

Creates a dedicated inference endpoint in the specified region. The endpoint is globally accessible via a unique URL.

Get Deployment#

GET /api/deployments/{deploymentId}

Delete Deployment#

DELETE /api/deployments/{deploymentId}

Start Deployment#

POST /api/deployments/{deploymentId}/start

Resume a stopped deployment.

Stop Deployment#

POST /api/deployments/{deploymentId}/stop

Stop serving requests by setting the service's minimum and maximum instances to zero.

Health Check#

GET /api/deployments/{deploymentId}/health

Returns the health status of the deployment endpoint.

Run Inference on Deployment#

POST /api/deployments/{deploymentId}/predict

Send an image directly to a deployment endpoint for inference. Functionally equivalent to model predict, but routed through the dedicated endpoint for lower latency.

Multipart Form:

Provide either file or source. The response uses the same image and metadata contract as model prediction and never returns the internal model path.

Get Metrics#

GET /api/deployments/{deploymentId}/metrics

Returns request counts, latency, and error rate metrics with sparkline data.

Query Parameters:

Get Logs#

GET /api/deployments/{deploymentId}/logs

Query Parameters:

Export API#

Convert models to optimized formats like ONNX, TensorRT, CoreML, and LiteRT for edge deployment. See Deploy documentation.

List Exports#

GET /api/exports

Query Parameters:

Create Export#

POST /api/exports

Body:

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

Supported Formats:

Use the format argument from the shared export table below. PyTorch is the source format and is not an API export target.

Get Export Status#

GET /api/exports/{exportId}

Cancel Export#

DELETE /api/exports/{exportId}

Track Export Download#

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

Activity API#

View a feed of recent actions on your account — training runs, uploads, and more. See Activity documentation.

List Activity#

GET /api/activity

Query Parameters:

Mark Events Seen#

POST /api/activity/mark-seen

Body:

{
    "all": true
}

Or pass specific IDs:

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

Pass the optional owner query parameter to mark events in a workspace.

Archive Events#

POST /api/activity/archive

Body:

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

Or pass specific IDs:

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

Pass the optional owner query parameter to archive or restore workspace events.

Trash API#

View and restore deleted items. Items are permanently removed after 30 days. See Trash documentation.

List Trash#

GET /api/trash

Query Parameters:

Restore Item#

POST /api/trash

Body:

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

Permanently Delete Item#

DELETE /api/trash

Body:

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

Empty Trash#

DELETE /api/trash/empty

Permanently deletes all items in trash.

Billing API#

Check your credit balance, plan usage, and transaction history. See Billing documentation.

The balance and transaction endpoints accept an optional owner query parameter with the workspace owner's username.

Get Balance#

GET /api/billing/balance

Response:

{
    "creditsCents": 2500,
    "plan": "free"
}

Get Usage Summary#

GET /api/billing/usage-summary

Returns plan details, limits, and usage metrics.

Get Transactions#

GET /api/billing/transactions

Returns transaction history (most recent first).

Transactions include client-facing ledger fields such as amount, resulting balance, date, optional model context, and receipt URL. Internal notes, Stripe payment/refund IDs, and idempotency keys are not returned.

Storage API#

Check your storage usage breakdown by category (datasets, models, exports) and see your largest items.

Get Storage Info#

GET /api/storage

Query Parameters:

Response:

{
    "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"
            }
        ]
    }
}

Cloud Storage Integrations#

Connect and browse read-only GCS, S3, or Azure Blob storage integrations:

GET /api/integrations/buckets
POST /api/integrations/buckets
POST /api/integrations/buckets/discover
GET /api/integrations/buckets/{id}/objects

All four operations accept the optional owner query parameter for a workspace. Object browsing also accepts required target plus optional prefix and provider cursor query parameters. Connection and discovery request bodies use the provider credential schemas in the interactive OpenAPI reference; credentials are never returned.

Upload API#

Upload files directly to cloud storage using signed URLs for fast, reliable transfers. Completing a model upload attaches its weights. Completing a dataset archive upload records the session; pass that sessionId to POST /api/datasets/ingest to start processing. See Data documentation.

Get Signed Upload URL#

POST /api/upload/signed-url

Request a signed URL for uploading a file directly to cloud storage. The signed URL bypasses the API server for large file transfers.

Body:

{
    "assetType": "datasets",
    "assetId": "dataset_abc123",
    "filename": "my-dataset.zip",
    "contentType": "application/zip",
    "totalBytes": 52428800
}

Response:

{
    "sessionId": "session_abc123",
    "uploadUrl": "https://storage.example.com/...",
    "expiresAt": "2026-02-22T12:00:00Z"
}

Complete Upload#

POST /api/upload/complete

Notify the platform that a file upload is complete. For models, this attaches the uploaded weights. For dataset archives, this verifies and records the upload session; call POST /api/datasets/ingest afterward to start dataset processing.

Body:

{
    "sessionId": "session_abc123",
    "checksum": "<optional sha-256 hex>"
}

Integrations API#

Import datasets from third-party services. See Integrations documentation.

Preview Roboflow Import#

POST /api/integrations/roboflow/preview

Resolve a Roboflow API key to a bulk-import plan: workspace info, which projects would be newly imported, count of already-imported versions (skipped), and unsupported project types. The Roboflow API key is passed in the body and is not persisted.

Import from Roboflow#

POST /api/integrations/roboflow/import

Queue dataset ingest jobs to import the selected Roboflow projects into your workspace. Requires storage headroom, and each dataset must fit your plan's per-import size limit.

API Keys API#

Manage your API keys for programmatic access. See API Keys documentation.

List API Keys#

GET /api/api-keys

API-key-authenticated clients receive key metadata, never decrypted existing key values. A newly created key is returned once by POST /api/api-keys.

Pass the optional owner query parameter to manage keys for a workspace where you have editor access.

Create API Key#

POST /api/api-keys

Body:

{
    "name": "training-server"
}

Delete API Key#

DELETE /api/api-keys

Query Parameters:

Example:

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

Teams & Members API#

Create team workspaces, invite members, and manage roles for collaboration. See Teams documentation.

List Teams#

GET /api/teams

Create Team#

POST /api/teams/create

Body:

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

List Members#

GET /api/members

Returns members of the current workspace.

Invite Member#

POST /api/members

Body:

{
    "email": "user@example.com",
    "role": "editor"
}

Update Member Role#

PATCH /api/members/{userId}

Remove Member#

DELETE /api/members/{userId}

Transfer Ownership#

POST /api/members/transfer-ownership

Explore API#

Search and browse public datasets and projects shared by the community. See Explore documentation.

Search Public Content#

GET /api/explore/search

Query Parameters:

Sidebar Data#

GET /api/explore/sidebar

Returns curated content for the Explore sidebar.

User & Settings APIs#

Manage your profile, API keys, storage usage, and team workspaces. See Settings documentation.

Account Summary#

GET /api/account/summary

Returns the authenticated account's plan, credit balance, resource counts, and team workspaces.

Get User by Username#

GET /api/users

Query Parameters:

Follow or Unfollow User#

PATCH /api/users

Body:

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

Check Username Availability#

GET /api/username/check

Query Parameters:

Settings#

GET /api/settings
POST /api/settings

Get or update user profile settings (display name, bio, social links, etc.).

Workspace Icon#

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

Upload a WebP profile/workspace icon up to 5 MB as multipart form field image, or remove it. Pass optional owner for a team workspace.

Python Integration#

For easier integration, use the Ultralytics Python package which handles authentication, uploads, and real-time metric streaming automatically.

Installation & Setup#

pip install "ultralytics>=8.4.104"

Verify installation:

yolo check

Authentication#

yolo login YOUR_API_KEY

Using Platform Datasets#

Reference datasets with ul:// URIs:

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,
)

URI Format:

Pushing to Platform#

Send results to a Platform project:

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",
)

What syncs:

• Training metrics (real-time)
• Final model weights
• Validation plots
• Console output
• System metrics

API Examples#

Load a model from Platform:

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

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

Run inference:

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 model:

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

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

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

Validation:

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

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

FAQ#

How do I paginate large results?#

Most endpoints use a limit parameter to control how many results are returned per request:

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

The Activity and Trash endpoints also support a page parameter for page-based pagination:

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

The Explore Search endpoint uses offset instead of page, with a fixed page size of 20:

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

Can I use the API without an SDK?#

The public REST operations documented above are available without the Python SDK. The SDK is a convenience wrapper that adds features like real-time metric streaming and automatic model uploads. You can explore the machine-readable contract interactively at platform.ultralytics.com/api/docs; browser-session-only account flows remain in the Platform UI.

Are there API client libraries?#

Use the Ultralytics Python package or make direct HTTP requests from any language.

How do I handle rate limits?#

Use the Retry-After header from the 429 response to wait the right amount of time:

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 RuntimeError("Rate limit exceeded")

How do I find my model or dataset ID?#

Resource IDs are returned by create, list, and get API responses. Platform page URLs use human-readable slugs, not database IDs:

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

Use the list endpoints to find the corresponding _id for a model, dataset, project, deployment, or other resource.