Link to this sectionREST 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

Link to this sectionAPI 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

Link to this sectionAuthentication#

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.

Link to this sectionGet API Key#

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

See API Keys for detailed instructions.

Link to this sectionAuthorization Header#

Include your API key in all requests:

Authorization: Bearer YOUR_API_KEY

Link to this sectionExample#

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

Link to this sectionBase URL#

All API endpoints use:

https://platform.ultralytics.com/api

Link to this sectionRate Limits#

The API enforces per-API-key rate limits (sliding-window, Upstash Redis-backed) to protect against abuse while keeping legitimate usage unrestricted. Anonymous traffic is additionally protected by Vercel's platform-level abuse controls.

When throttled, the API returns 429 with retry metadata:

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

Link to this sectionPer 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.

Link to this sectionDedicated Endpoints (Unlimited)#

Dedicated endpoints are not subject to API key rate limits. When you deploy a model to a dedicated endpoint, requests to that endpoint URL (e.g., https://predict-abc123.run.app/predict) go directly to your dedicated service with no rate limiting from the Platform. You're paying for the compute, so you get throughput from your dedicated service configuration rather than the shared API limits.

Link to this sectionResponse Format#

Link to this sectionSuccess Responses#

Responses return JSON with resource-specific fields:

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

Link to this sectionError Responses#

{
    "error": "Dataset not found"
}

Link to this sectionDatasets API#

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

Link to this sectionList 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"
}

Link to this sectionGet 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.

Link to this sectionCreate 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"
}

Link to this sectionUpdate Dataset#

PATCH /api/datasets/{datasetId}

Body (partial update):

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

Link to this sectionDataset 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.

Link to this sectionDelete Dataset#

DELETE /api/datasets/{datasetId}

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

Link to this sectionClone 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"
}

Link to this sectionExport 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
}

Link to this sectionCreate Dataset Version#

POST /api/datasets/{datasetId}/export

Create a new numbered version snapshot of the dataset. Owner-only. 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=..."
}

Link to this sectionUpdate Version Description#

PATCH /api/datasets/{datasetId}/export

Update the description of an existing version. Owner-only.

Request Body:

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

Response:

{
    "ok": true
}

Link to this sectionRestore 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
}

Link to this sectionGet 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
}

Link to this sectionManage 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]
}

Link to this sectionRedistribute 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
}

Link to this sectionDataset 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.

Link to this sectionImage 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).

Link to this sectionGet 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
}

Link to this sectionAuto-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:

Link to this sectionDataset 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

Link to this sectionDataset Images#

Link to this sectionList Images#

GET /api/datasets/{datasetId}/images

Query Parameters:

Link to this sectionGet 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"]
}

Link to this sectionGet Signed Image URLs#

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

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

Link to this sectionDelete Image#

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

Link to this sectionGet Image Labels#

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

Returns annotations and class names for a specific image.

Link to this sectionUpdate 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] }
    ]
}

Link to this sectionBulk 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

Link to this sectionProjects API#

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

Link to this sectionList Projects#

GET /api/projects

Query Parameters:

Link to this sectionGet Project#

GET /api/projects/{projectId}

Link to this sectionCreate 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

Link to this sectionUpdate Project#

PATCH /api/projects/{projectId}

Link to this sectionDelete Project#

DELETE /api/projects/{projectId}

Soft-deletes the project (moved to trash).

Link to this sectionClone 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.

Link to this sectionProject 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.

Link to this sectionModels API#

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

Link to this sectionList Models#

GET /api/models

Query Parameters:

Link to this sectionList 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.

Link to this sectionGet Model#

GET /api/models/{modelId}

Link to this sectionCreate Model#

POST /api/models

JSON Body:

Link to this sectionUpdate Model#

PATCH /api/models/{modelId}

Link to this sectionDelete Model#

DELETE /api/models/{modelId}

Link to this sectionDownload Model Files#

GET /api/models/{modelId}/files

Returns signed download URLs for model files.

Link to this sectionClone 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"
}

Link to this sectionTrack Download#

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

Track model download analytics.

Link to this sectionRun 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 semantic mask data, 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
    }
}

Link to this sectionTraining 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

Link to this sectionStart 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

Link to this sectionGet 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.

Link to this sectionGet 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.

Link to this sectionCancel Training#

DELETE /api/models/{modelId}/training

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

Link to this sectionDeployments 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

Link to this sectionList Deployments#

GET /api/deployments

Query Parameters:

Link to this sectionCreate 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.

Link to this sectionGet Deployment#

GET /api/deployments/{deploymentId}

Link to this sectionDelete Deployment#

DELETE /api/deployments/{deploymentId}

Link to this sectionStart Deployment#

POST /api/deployments/{deploymentId}/start

Resume a stopped deployment.

Link to this sectionStop Deployment#

POST /api/deployments/{deploymentId}/stop

Pause a running deployment (stops billing).

Link to this sectionHealth Check#

GET /api/deployments/{deploymentId}/health

Returns the health status of the deployment endpoint.

Link to this sectionRun 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.

Link to this sectionGet Metrics#

GET /api/deployments/{deploymentId}/metrics

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

Query Parameters:

Link to this sectionGet Logs#

GET /api/deployments/{deploymentId}/logs

Query Parameters:

Link to this sectionExport API#

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

Link to this sectionList Exports#

GET /api/exports

Query Parameters:

Link to this sectionCreate 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:

Link to this sectionGet Export Status#

GET /api/exports/{exportId}

Link to this sectionCancel Export#

DELETE /api/exports/{exportId}

Link to this sectionTrack Export Download#

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

Link to this sectionActivity API#

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

Link to this sectionList Activity#

GET /api/activity

Query Parameters:

Link to this sectionMark 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.

Link to this sectionArchive 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.

Link to this sectionTrash API#

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

Link to this sectionList Trash#

GET /api/trash

Query Parameters:

Link to this sectionRestore Item#

POST /api/trash

Body:

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

Link to this sectionPermanently Delete Item#

DELETE /api/trash

Body:

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

Link to this sectionEmpty Trash#

DELETE /api/trash/empty

Permanently deletes all items in trash.

Link to this sectionBilling API#

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

Link to this sectionGet Balance#

GET /api/billing/balance

Query Parameters:

Response:

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

Link to this sectionGet Usage Summary#

GET /api/billing/usage-summary

Returns plan details, limits, and usage metrics.

Link to this sectionGet 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.

Query Parameters:

Link to this sectionStorage API#

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

Link to this sectionGet 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"
            }
        ]
    }
}

Link to this sectionCloud 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.

Link to this sectionUpload 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.

Link to this sectionGet 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"
}

Link to this sectionComplete 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>"
}

Link to this sectionIntegrations API#

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

Link to this sectionPreview 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.

Link to this sectionImport 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.

Link to this sectionAPI Keys API#

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

Link to this sectionList 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.

Link to this sectionCreate API Key#

POST /api/api-keys

Body:

{
    "name": "training-server"
}

Link to this sectionDelete 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"

Link to this sectionTeams & Members API#

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

Link to this sectionList Teams#

GET /api/teams

Link to this sectionCreate Team#

POST /api/teams/create

Body:

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

Link to this sectionList Members#

GET /api/members

Returns members of the current workspace.

Link to this sectionInvite Member#

POST /api/members

Body:

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

Link to this sectionUpdate Member Role#

PATCH /api/members/{userId}

Link to this sectionRemove Member#

DELETE /api/members/{userId}

Link to this sectionTransfer Ownership#

POST /api/members/transfer-ownership

Link to this sectionExplore API#

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

Link to this sectionSearch Public Content#

GET /api/explore/search

Query Parameters:

Link to this sectionSidebar Data#

GET /api/explore/sidebar

Returns curated content for the Explore sidebar.

Link to this sectionUser & Settings APIs#

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

Link to this sectionAccount Summary#

GET /api/account/summary

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

Link to this sectionGet User by Username#

GET /api/users

Query Parameters:

Link to this sectionFollow or Unfollow User#

PATCH /api/users

Body:

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

Link to this sectionCheck Username Availability#

GET /api/username/check

Query Parameters:

Link to this sectionSettings#

GET /api/settings
POST /api/settings

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

Link to this sectionWorkspace 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.

Link to this sectionError Codes#

Link to this sectionPython Integration#

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

Link to this sectionInstallation & Setup#

pip install ultralytics

Verify installation:

yolo check

Link to this sectionAuthentication#

yolo settings api_key=YOUR_API_KEY

Link to this sectionUsing 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:

Link to this sectionPushing 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

Link to this sectionAPI 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)

Validation:

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

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

Link to this sectionFAQ#

Link to this sectionHow 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"

Link to this sectionCan 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.

Link to this sectionAre there API client libraries?#

Currently, use the Ultralytics Python package or make direct HTTP requests. Official client libraries for other languages are planned.

Link to this sectionHow 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 Exception("Rate limit exceeded")

Link to this sectionHow do I find my model or dataset ID?#

Resource IDs are returned when you create resources via the API. You can also find them in the platform URL:

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

Use the list endpoints to search by name or filter by project.