Ultralytics Platform MCP

Start an auto-annotation run on a dataset by slug, owner/slug, or a ul://owner/datasets/slug URI, labelling it with a model given by owner/project/model, ul://owner/project/model, or slug with a project (state-changing, billable, may cost credits). Requires confirm_cost=true: there is no cost preview, no published rate, and a 402 signals insufficient credits; gauge magnitude with datasets_get (the unlabeled image count by default, the total count when include_annotated is true). Sends only modelId plus any of confidence, iou, class_mapping, and include_annotated the caller sets explicitly, omitting the rest so the server's own defaults (confidence 0.25, iou 0.7, include_annotated false, illustrative only) apply undisturbed. There is no imgsz parameter. class_mapping bridges a model/dataset class-taxonomy mismatch (for example a 1-class model against an 80-class dataset, which otherwise fails outright); it passes through with no length check. Labels are additive, never overwritten, so no overwrite confirmation is needed. Every start snapshots a dataset version before labelling, listed via datasets_get and undoable exactly with dataset_version_restore. Billing settles at run time, not at dismissal, so auto_annotate_stop does not refund a charge already incurred. Use auto_annotate_status to poll and auto_annotate_stop to cancel.

Get an auto-annotation run's status for a dataset by slug, owner/slug, or a ul://owner/datasets/slug URI. Surfaces activeJob and lastRun unmodified: both null means the dataset has never run one; activeJob carries progress for a run in flight; lastRun carries failed/stopped booleans plus results, or an error when the run failed.

Stop or dismiss a dataset's auto-annotation run by slug, owner/slug, or a ul://owner/datasets/slug URI. Reads status first and refuses without calling the endpoint when no run is active, since there is nothing to stop. When a run is active it sends the request and surfaces the server's own action verbatim rather than inferring it: cancelled for an active run stopped mid-flight, dismissed for a terminal run's summary being cleared, or none if nothing acted on. Ships ungated, consistent with training_cancel and export_cancel: an off-switch is never gated. An undismissed terminal run does not block the next start, so this never strands anything; dismissal moves no money.

Get per-class annotation counts for a dataset by slug, owner/slug, or a ul://owner/datasets/slug URI. By default omits the bulky histogram and heatmap groups (image size, file size, format, points-per-annotation, bbox distributions, and location/dimension heatmaps), naming them in the summary; pass include_histograms: true to get the full payload unmodified.

Get a time-limited export download link for a dataset by slug, owner/slug, or a ul://owner/datasets/slug URI, for the latest export or one frozen version.

List images in a dataset by slug, owner/slug, or a ul://owner/datasets/slug URI with optional filtering.

Start a remote URL ingest job for a dataset by slug, owner/slug, or a ul://owner/datasets/slug URI. Defaults conflictPolicy to skip (the platform default is undocumented). Reports the queued job id with the dataset's current ingest status; use datasets_get to follow up.

Upload a local dataset archive through the signed-upload flow for a dataset by slug, owner/slug, or a ul://owner/datasets/slug URI. Defaults conflictPolicy to skip (the platform default is undocumented). Reports the queued job id with the dataset's current ingest status; use datasets_get to follow up.

Upload a local image folder as a zip through the signed-upload flow for a dataset by slug, owner/slug, or a ul://owner/datasets/slug URI. Defaults conflictPolicy to skip (the platform default is undocumented). Reports the queued job id with the dataset's current ingest status; use datasets_get to follow up.

Upload a local video as extracted frames through the signed-upload flow for a dataset by slug, owner/slug, or a ul://owner/datasets/slug URI. Defaults conflictPolicy to skip (the platform default is undocumented). Reports the queued job id with the dataset's current ingest status; use datasets_get to follow up.

Create a frozen dataset version snapshot by slug, owner/slug, or a ul://owner/datasets/slug URI. If the dataset is unchanged since the previous snapshot the existing version is returned instead of a new one.

Restore a dataset to a previously saved version by slug, owner/slug, or a ul://owner/datasets/slug URI, and an integer version number. Versions are listed via datasets_get (the versions array, already returned unprojected). This REPLACES the dataset's current images, labels, and splits with that snapshot outright: anything done since that version, including un-versioned manual annotation work, is discarded. Ships ungated anyway, since it is the undo tool — an auto-annotate run snapshots a version before labelling, so restoring that version undoes the run exactly, and a mistaken restore is itself recoverable by restoring a later version. Restore also reassigns image IDs: a pre-restore image ID still resolves afterward but returns an empty label array rather than a 404, so callers must re-list images (for example with dataset_images_list) after a restore instead of reusing held IDs.

Create a dataset in your Ultralytics workspace. Defaults to private visibility (the platform defaults to public when visibility is omitted).

Delete a dataset by slug, owner/slug, or a ul://owner/datasets/slug URI. Deleting a dataset moves its images and annotations to trash with it; models trained on it are not deleted. Trashed items remain restorable for a bounded window.

Get details for one dataset by slug, owner/slug, or a ul://owner/datasets/slug URI.

List datasets in your Ultralytics workspace.

Get details for one deployment by owner/deployment or a bare slug (owner defaults to the account owner). serviceUrl and deployedAt are null until the deployment reaches status ready.

Probe one deployment's health by owner/deployment or a bare slug (owner defaults to the account owner). status is the upstream HTTP status the health probe observed at the deployment's own service URL, not the status of this tool call.

Read log entries for one deployment by owner/deployment or a bare slug (owner defaults to the account owner). severity is passed through to the server unvalidated (illustrative values: DEBUG, INFO, NOTICE, WARNING, ERROR, CRITICAL, ALERT, EMERGENCY); an invalid value returns the server's own rejection message. limit defaults to 50, max 200. nextPageToken pages through older entries.

Read metrics for one deployment by owner/deployment or a bare slug (owner defaults to the account owner). The response is one of two shapes selected by sparkline: the default shape carries timeRange (a {start, end} object)/summary/timeSeries, sparkline=true carries requests24h (an array of per-hour points, not a total)/totalRequests/errorRate/avgLatencyMs. The two are never merged; which shape came back is returned as-is. range (e.g. 1h, 24h, 7d; default 24h) is passed through to the server unvalidated.

Run inference through a deployment's own serving endpoint on a local image or video file, by owner/deployment or a bare slug (owner defaults to the account owner). Returns images/metadata verbatim, including undocumented metadata fields. No per-request cost is documented for this endpoint; costs follow the deployment's own resource configuration. A cold start on a scaled-to-zero deployment may respond slowly or with a 503 — check deployment_health rather than retrying blindly.

Stop a deployment by owner/deployment or a bare slug (owner defaults to the account owner). Sends only {action: stop}; the endpoint's start/resize/replace actions are unreachable from this tool. Stopping preserves the deployment's URL and configuration and still counts toward deployment quota; it is a money-off switch and ships ungated, consistent with training_cancel and export_cancel. Stopping an already-stopped deployment is rejected by the server (400) rather than treated as a success. Reversing this (start) is not available in this tool set.

List model deployments in your Ultralytics workspace.

Search public datasets on Ultralytics Explore.

Search public projects on Ultralytics Explore.

Cancel an active export job for a model by owner/project/model, ul://owner/project/model, or slug with a project, plus the export id. Checks the export's status first and sends the cancellation only while it is still active, refusing on any terminal status; the same API verb deletes a finished export's artifact irreversibly instead of cancelling it. The status check cannot be atomic: an export that finishes between the check and the request will have its artifact deleted rather than cancelled, and that deletion cannot be undone.

Create a model export job by owner/project/model, ul://owner/project/model, or slug with a project (state-changing, may cost credits). The format is validated immediately by the server; task and architecture compatibility is only known when the job runs, so a queued export can still fail. Use export_status and exports_list for the real outcome. Requires confirm_cost=true.

Get one export job's status for a model by owner/project/model, ul://owner/project/model, or slug with a project, plus the export id.

List export jobs for a model by owner/project/model, ul://owner/project/model, or slug with a project.

Get current cloud-GPU stock status by GPU type.

Download a trained model's weight file to an explicit local path by owner/project/model, ul://owner/project/model, or slug with a project.

Report a model's best training epoch and its reported metrics, labelled so neither can be mistaken for the other (works for private and public projects). bestEpoch, bestFitness, and bestEpochMetrics are stated only when exactly one trainResults record has the reported bestEpoch and that record's fitness exactly equals the reported bestFitness; otherwise all three are null and bestEpochNote keeps the platform's raw values and says why (older Ultralytics versions reported the last epoch as bestEpoch). reportedMetrics is the model's top-level metrics field verbatim; the API does not say which evaluation produced it (on finished Platform-trained runs observed live it matches the post-training evaluation of the best checkpoint, not the last training epoch), so it makes no epoch claim. resultRecordCount counts trainResults records, not epochs. include_train_args adds the full trainArgs object (111 keys observed live), omitted by default. include_history adds the last N records in API order and always states the window it covers, with record counts, the min/max reported epoch, and duplicate and missing epoch numbers in that range.

Report a model's evaluation plots (per-class pr_curve, f1_curve, precision_curve, recall_curve, confusion_matrix), which model_metrics and training_monitor do not surface. By default lists each plot's type and the shape of its fields (array lengths only, never the values) since one pr_curve alone can carry thousands of numbers on a multi-class model; pass type to get that one plot's data back exactly as the platform returned it, unmodified. Field shapes vary by type: pr_curve/f1_curve/precision_curve/recall_curve carry x/y (and pr_curve additionally ap); confusion_matrix carries a matrix field instead, not x/y/ap. Plot presence does not track training history: a model can have plots with no trainResults, or (rarely) plots: [] on an otherwise completed model.

Run inference with a trained model on an image URL or base64 image (`source`), or on a local image or video file (`file_path`). Give exactly one.

Soft-delete a model by owner/project/model, ul://owner/project/model, or slug with a project. Deleted models go to trash and remain restorable; weights, training history, and exports are removed only on permanent deletion.

Get details for one model by owner/project/model, ul://owner/project/model, or slug with a project. Model quality (best epoch and fitness) is not included; use model_metrics, which validates the platform's best-epoch fields.

List models in a project by slug, owner/slug, or project ul:// URI. Model quality is not included; use model_metrics, which validates the platform's best-epoch fields.

Create a project in your Ultralytics workspace. Defaults to private visibility (the platform defaults to public when visibility is omitted).

Soft-delete a project by slug, owner/slug, or project ul:// URI. Deleted projects land in trash and remain restorable for a bounded window.

Get details for one project by slug, owner/slug, or project ul:// URI.

List computer-vision projects in your Ultralytics workspace.

Cancel a running training job by owner/project/model, ul://owner/project/model, or slug with a project. Cancelling releases the compute instance; elapsed GPU time is still charged and the most recently uploaded checkpoint is preserved rather than discarded. This stops the job and does not delete the model.

Report a model's training status and progress (works for private and public projects). reportedCurrentEpoch, reportedProgressPercentage, and etaMs are the training job's own counters, passed through verbatim; after a run ends reportedCurrentEpoch can count a post-training evaluation as an epoch, so it may be one higher than the epochs actually trained, with reportedProgressPercentage inflated to match, and etaMs can stay nonzero. With no training job, progress is reported unavailable rather than inferred. resultRecordCount counts trainResults records, which are not epochs: a history can include a post-training evaluation record, duplicate or missing epoch numbers, and records out of epoch order. lastReportedMetrics is the last record in API order with its reported epoch, not necessarily the latest epoch. Model quality (best epoch, the model's reported metrics) belongs to model_metrics. timing.elapsedMs is wall-clock since model creation, evaluated at request time: it tracks elapsed run time while training is active, but for a finished model it reflects the model's age, not training duration. Billed training time is computeCost.durationMs.

Start a cloud training job from an existing model or official YOLO base checkpoint (state-changing, may cost credits). Trains on exactly one dataset and requires epochs. The dataset is validated immediately, so an unusable dataset is rejected before any compute starts. In checkpoint mode a project model is created first, then the checkpoint's task is checked against the dataset's task server-side when training starts, by which point the model already exists — a mismatch there still leaves that model behind, unrequested, and the error names it so it can be reviewed and deleted (models_delete) if unwanted. Starting is billable immediately: the platform has no cost preview before that, so the projected cost and remaining balance are only reported after the job starts. Training an existing model that already has a recorded run (any status past pending/untrained) replaces that model's status, epoch count, and training result history the instant the new job starts, and that history cannot be recovered afterward; the previously uploaded weights survive. That path requires confirm_history_loss=true in addition to confirm_cost=true. Checkpoint mode never destroys an existing model's history since it always creates a new one, so it never needs confirm_history_loss — its own risk is the possible leftover model described above. An untrained or never-trained model needs no extra confirmation either. Use training_cancel to stop a job that is already running. Requires confirm_cost=true.