---
plans: [free, pro, enterprise]
comments: true
description: Complete REST API reference for Ultralytics Platform including authentication, endpoints, and examples for datasets, models, and deployments.
keywords: Ultralytics Platform, REST API, API reference, authentication, endpoints, YOLO, programmatic access
integrations_path: ../../integrations
---

# REST API Reference

[Ultralytics Platform](https://platform.ultralytics.com) provides a comprehensive REST API for programmatic access to datasets, models, training, and deployments.

![Ultralytics Platform Interactive API Documentation](https://cdn.ul.run/i/902c8979434234a150d1d2df438ec1fb.avif)<!-- screenshot -->
!!! tip "Quick Start"

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

!!! tip "Interactive API Docs"

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

## API Overview

The API is organized around the core platform resources:

```mermaid
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
```

| Resource                                   | Description                   | Key Operations                                |
| ------------------------------------------ | ----------------------------- | --------------------------------------------- |
| [Datasets](../data/datasets.md)            | Labeled image collections     | CRUD, images, labels, export, versions, clone |
| [Projects](../train/projects.md)           | Training workspaces           | CRUD, clone, icon                             |
| [Models](../train/models.md)               | Trained checkpoints           | CRUD, predict, download, clone, export        |
| [Deployments](../deploy/endpoints.md)      | Dedicated inference endpoints | CRUD, start/stop, metrics, logs, health       |
| [Exports](../train/models.md#export-model) | Format conversion jobs        | Create, status, download                      |
| [Training](../train/cloud-training.md)     | Cloud GPU training jobs       | Start, status, cancel                         |
| [Billing](../account/billing.md)           | Credits and usage             | Balance, usage, transactions                  |
| [Teams](../account/teams.md)               | Workspace collaboration       | Workspaces, members, roles                    |

## 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](../account/api-keys.md) for detailed instructions.

### Authorization Header

Include your API key in all requests:

```http
Authorization: Bearer YOUR_API_KEY
```

!!! info "API Key Format"

    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.

### Example

=== "cURL"

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

=== "Python"

    ```python
    import requests

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

=== "JavaScript"

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

## Base URL

All API endpoints use:

```text
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:

```http
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:

| Category       | Limit            | Applies To                                                                                        |
| -------------- | ---------------- | ------------------------------------------------------------------------------------------------- |
| **Default**    | 100 requests/min | Routes not assigned to a category below                                                           |
| **Training**   | 10 requests/min  | Starting cloud training                                                                           |
| **Upload**     | 10 requests/min  | Signed upload URLs, upload completion, and dataset ingest                                         |
| **Predict**    | 20 requests/min  | Model and deployment inference through Platform API routes                                        |
| **Export**     | 20 requests/min  | Model export routes and dataset export/version routes                                             |
| **Download**   | 30 requests/min  | Model file downloads                                                                              |
| **Mutation**   | 10 requests/min  | Team creation, storage integration changes, API keys, members, invites, and deployment start/stop |
| **Billing**    | 5 requests/min   | Auto top-up and subscription checkout routes                                                      |
| **Hydrate**    | 20 requests/min  | Hydrating a selected set of dataset images                                                        |
| **Clustering** | 10 requests/min  | Dataset image clustering                                                                          |

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](../deploy/endpoints.md) 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.

!!! tip "Handling Rate Limits"

    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.

## Response Format

### Success Responses

Responses return JSON with resource-specific fields:

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

### Error Responses

```json
{
    "error": "Dataset not found"
}
```

| HTTP Status | Meaning                  |
| ----------- | ------------------------ |
| `200`       | Success                  |
| `201`       | Created                  |
| `400`       | Invalid request          |
| `401`       | Authentication required  |
| `403`       | Insufficient permissions |
| `404`       | Resource not found       |
| `409`       | Conflict (duplicate)     |
| `429`       | Rate limit exceeded      |
| `500`       | Server error             |

---

## Datasets API

Create, browse, and manage labeled image datasets for training YOLO models. See [Datasets documentation](../data/datasets.md).

### List Datasets

```http
GET /api/datasets
```

**Query Parameters:**

| Parameter          | Type    | Description                                                     |
| ------------------ | ------- | --------------------------------------------------------------- |
| `username`         | string  | Filter by username                                              |
| `limit`            | int     | Items per page (default: 1000, max: 1000)                       |
| `owner`            | string  | Workspace owner username                                        |
| `includeImageUrls` | boolean | Include signed full-size sample image URLs (default: `false`)   |
| `includeSamples`   | boolean | Set `false` to omit sample images and reduce the response size. |

=== "cURL"

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

=== "Python"

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

**Response:**

```json
{
    "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

```http
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

```http
POST /api/datasets
```

**Body:**

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

!!! note "Supported Tasks"

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

**Response:**

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

### Update Dataset

```http
PATCH /api/datasets/{datasetId}
```

**Body (partial update):**

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

### Dataset Icon

```http
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

```http
DELETE /api/datasets/{datasetId}
```

Soft-deletes the dataset (moved to [trash](../account/trash.md), recoverable for 30 days).

### Clone Dataset

```http
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):**

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

### Export Dataset

```http
GET /api/datasets/{datasetId}/export
```

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

**Query Parameters:**

| Parameter | Type    | Description                                                                                                             |
| --------- | ------- | ----------------------------------------------------------------------------------------------------------------------- |
| `v`       | integer | Version number (1-indexed). If omitted, returns the latest mutable export, reusing it when the dataset has not changed. |

**Response:**

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

### Create Dataset Version

```http
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:**

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

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

**Response:**

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

### Update Version Description

```http
PATCH /api/datasets/{datasetId}/export
```

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

**Request Body:**

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

**Response:**

```json
{
    "ok": true
}
```

### Restore Dataset Version

```http
POST /api/datasets/{datasetId}/restore
```

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

```json
{
    "version": 2
}
```

### Get Class Statistics

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

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

**Response:**

```json
{
    "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):

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

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

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

Delete classes:

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

```json
{
    "classIds": [2, 4]
}
```

### Redistribute Splits

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

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

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

### Dataset Embeddings

```http
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

```http
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

```http
GET /api/datasets/{datasetId}/models
```

Returns models that were trained using this dataset.

**Response:**

```json
{
    "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

```http
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:**

| Field        | Type   | Required | Description                                                                                                                                       |
| ------------ | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `imageHash`  | string | Yes      | Hash of the image to annotate                                                                                                                     |
| `modelId`    | string | No       | Model to use for inference, as a `ul://` URI (e.g. `ul://username/project/model`). If omitted, the dataset's task-specific default model is used. |
| `confidence` | float  | No       | Confidence threshold (default: 0.25)                                                                                                              |
| `iou`        | float  | No       | IoU threshold (default: 0.7)                                                                                                                      |

### Dataset Ingest

```http
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):**

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

**Body (remote archive or NDJSON):**

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

**Body (later ingest, importing labels):**

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

!!! note "Class Mapping"

    The first ingest creates classes from the archive automatically. On later ingests, archive classes omitted from `classMapping` first fall back to a case-insensitive match against existing dataset classes. Labels are skipped only for classes explicitly mapped to `null` or without a matching existing class.

**Response:**

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

```mermaid
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

```http
GET /api/datasets/{datasetId}/images
```

**Query Parameters:**

| Parameter           | Type   | Description                                                                                                                                                                                                    |
| ------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `split`             | string | Filter by split: `train`, `val`, `test`                                                                                                                                                                        |
| `offset`            | int    | Pagination offset (default: 0)                                                                                                                                                                                 |
| `limit`             | int    | Items per page (default: 50, max: 5000)                                                                                                                                                                        |
| `sort`              | string | Sort order: `newest`, `oldest`, `name-asc`, `name-desc`, `height-asc`, `height-desc`, `width-asc`, `width-desc`, `size-asc`, `size-desc`, `labels-asc`, `labels-desc` (some disabled for >100k image datasets) |
| `hasLabel`          | string | Filter by label status (`true` or `false`)                                                                                                                                                                     |
| `hasError`          | string | Filter by error status (`true` or `false`)                                                                                                                                                                     |
| `search`            | string | Search by filename or image hash                                                                                                                                                                               |
| `classIds`          | string | Comma-separated class IDs; returns images containing any of the specified classes                                                                                                                              |
| `includeThumbnails` | string | Include signed thumbnail URLs (default: `true`)                                                                                                                                                                |
| `includeImageUrls`  | string | Include signed full image URLs (default: `false`)                                                                                                                                                              |

#### Get Selected Images

```http
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.

```json
{
    "imageIds": ["IMAGE_OBJECT_ID"]
}
```

#### Get Signed Image URLs

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

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

#### Delete Image

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

#### Get Image Labels

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

Returns annotations and class names for a specific image.

#### Update Image Labels

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

**Body:**

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

!!! info "Coordinate Format"

    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, ...]`.

#### Bulk Image Operations

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

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

Bulk delete images:

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

---

## Projects API

Organize your models into projects. Each model belongs to one project. See [Projects documentation](../train/projects.md).

### List Projects

```http
GET /api/projects
```

**Query Parameters:**

| Parameter  | Type   | Description              |
| ---------- | ------ | ------------------------ |
| `username` | string | Filter by username       |
| `limit`    | int    | Items per page           |
| `owner`    | string | Workspace owner username |

### Get Project

```http
GET /api/projects/{projectId}
```

### Create Project

```http
POST /api/projects
```

=== "cURL"

    ```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"

    ```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"]
    ```

### Update Project

```http
PATCH /api/projects/{projectId}
```

### Delete Project

```http
DELETE /api/projects/{projectId}
```

Soft-deletes the project (moved to [trash](../account/trash.md)).

### Clone Project

```http
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

```http
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](../train/models.md).

### List Models

```http
GET /api/models
```

**Query Parameters:**

| Parameter   | Type   | Required | Description                       |
| ----------- | ------ | -------- | --------------------------------- |
| `projectId` | string | Yes      | Project ID (required)             |
| `fields`    | string | No       | Field set: `summary`, `charts`    |
| `ids`       | string | No       | Comma-separated model IDs         |
| `limit`     | int    | No       | Max results (default 20, max 100) |

### List Completed Models

```http
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

```http
GET /api/models/{modelId}
```

### Create Model

```http
POST /api/models
```

**JSON Body:**

| Field         | Type   | Required | Description                                                       |
| ------------- | ------ | -------- | ----------------------------------------------------------------- |
| `projectId`   | string | Yes      | Target project ID                                                 |
| `slug`        | string | No       | URL slug (lowercase alphanumeric/hyphens)                         |
| `name`        | string | No       | Display name (max 100 chars)                                      |
| `description` | string | No       | Model description (max 1000 chars)                                |
| `task`        | string | No       | Task type (detect, segment, semantic, depth, pose, obb, classify) |

!!! note "Model File Upload"

    To attach `.pt` weights, request a signed upload URL with `assetType: models` and this model's ID as `assetId`, upload the file, then call `POST /api/upload/complete` with the returned `sessionId`.

### Update Model

```http
PATCH /api/models/{modelId}
```

### Delete Model

```http
DELETE /api/models/{modelId}
```

### Download Model Files

```http
GET /api/models/{modelId}/files
```

Returns signed download URLs for model files.

### Clone Model

```http
POST /api/models/{modelId}/clone
```

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

**Body:**

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

| Field               | Type   | Required | Description                           |
| ------------------- | ------ | -------- | ------------------------------------- |
| `targetProjectSlug` | string | Yes      | Destination project slug              |
| `modelName`         | string | No       | Name for the cloned model             |
| `description`       | string | No       | Model description                     |
| `owner`             | string | No       | Team username (for workspace cloning) |

### Track Download

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

Track model download analytics.

### Run Inference

```http
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:**

{% include "macros/platform-inference-parameters.md" %}

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

=== "cURL"

    ```bash
    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
    ```

=== "Python"

    ```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"]
    ```

**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.

```json
{
    "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](../train/cloud-training.md).

```mermaid
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

```http
POST /api/training/start
```

=== "cURL"

    ```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"

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

!!! note "GPU Types"

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

### Get GPU Availability

```http
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

```http
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

```http
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](../deploy/endpoints.md).

!!! info "API-key support by route"

    All deployment routes below accept API-key authentication. For high-throughput 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.

```mermaid
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

```http
GET /api/deployments
```

**Query Parameters:**

| Parameter | Type   | Description                         |
| --------- | ------ | ----------------------------------- |
| `modelId` | string | Filter by model                     |
| `status`  | string | Filter by status                    |
| `limit`   | int    | Max results (default: 20, max: 100) |
| `owner`   | string | Workspace owner username            |

### Create Deployment

```http
POST /api/deployments
```

**Body:**

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

| Field       | Type   | Required | Description                                                                |
| ----------- | ------ | -------- | -------------------------------------------------------------------------- |
| `modelId`   | string | Yes      | Model ID to deploy                                                         |
| `name`      | string | Yes      | Deployment name                                                            |
| `region`    | string | Yes      | Deployment region                                                          |
| `resources` | object | No       | Resource configuration (`cpu`, `memoryGi`, `minInstances`, `maxInstances`) |

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

!!! note "Default Resources"

    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`.

!!! tip "Region Selection"

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

### Get Deployment

```http
GET /api/deployments/{deploymentId}
```

### Delete Deployment

```http
DELETE /api/deployments/{deploymentId}
```

### Start Deployment

```http
POST /api/deployments/{deploymentId}/start
```

Resume a stopped deployment.

### Stop Deployment

```http
POST /api/deployments/{deploymentId}/stop
```

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

### Health Check

```http
GET /api/deployments/{deploymentId}/health
```

Returns the health status of the deployment endpoint.

### Run Inference on Deployment

```http
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:**

{% include "macros/platform-inference-parameters.md" %}

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

```http
GET /api/deployments/{deploymentId}/metrics
```

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

**Query Parameters:**

| Parameter   | Type   | Description                                                   |
| ----------- | ------ | ------------------------------------------------------------- |
| `range`     | string | Time range: `1h`, `6h`, `24h` (default), `7d`, `30d`          |
| `sparkline` | string | Set to `true` for optimized sparkline data for dashboard view |

### Get Logs

```http
GET /api/deployments/{deploymentId}/logs
```

**Query Parameters:**

| Parameter   | Type   | Description                                                             |
| ----------- | ------ | ----------------------------------------------------------------------- |
| `severity`  | string | Comma-separated filter: `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL` |
| `limit`     | int    | Number of entries (default: 50, max: 200)                               |
| `pageToken` | string | Pagination token from previous response                                 |

---

## Export API

Convert models to optimized formats like ONNX, TensorRT, CoreML, and LiteRT for edge deployment. See [Deploy documentation](../deploy/index.md).

### List Exports

```http
GET /api/exports
```

**Query Parameters:**

| Parameter | Type   | Description                         |
| --------- | ------ | ----------------------------------- |
| `modelId` | string | Model ID (required)                 |
| `status`  | string | Filter by status                    |
| `limit`   | int    | Max results (default: 20, max: 100) |

### Create Export

```http
POST /api/exports
```

**Body:**

| Field     | Type   | Required    | Description                                                                                                                   |
| --------- | ------ | ----------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `modelId` | string | Yes         | Source model ID                                                                                                               |
| `format`  | string | Yes         | Export format (see table below)                                                                                               |
| `gpuType` | string | Conditional | Required when `format` is `engine`; use a supported [GPU or Jetson target](../train/models.md#nvidia-jetson-tensorrt-targets) |
| `args`    | object | No          | Export arguments (`imgsz`, `quantize`, `dynamic`, etc.)                                                                       |

=== "cURL"

    ```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"

    ```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"]
    ```

**Supported Formats:**

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

{% include "macros/export-table.md" %}

### Get Export Status

```http
GET /api/exports/{exportId}
```

### Cancel Export

```http
DELETE /api/exports/{exportId}
```

### Track Export Download

```http
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](../account/activity.md).

!!! note "API-key support by route"

    All Activity routes below accept API-key authentication.

### List Activity

```http
GET /api/activity
```

**Query Parameters:**

| Parameter  | Type    | Description                               |
| ---------- | ------- | ----------------------------------------- |
| `limit`    | int     | Page size (default: 20, max: 100)         |
| `page`     | int     | Page number (default: 1)                  |
| `archived` | boolean | `true` for Archive tab, `false` for Inbox |
| `search`   | string  | Case-insensitive search in event fields   |
| `start`    | date    | Include events on or after this date      |
| `end`      | date    | Include events on or before this date     |
| `export`   | boolean | Return all matching events as JSON        |
| `owner`    | string  | Workspace username                        |

### Mark Events Seen

```http
POST /api/activity/mark-seen
```

**Body:**

```json
{
    "all": true
}
```

Or pass specific IDs:

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

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

### Archive Events

```http
POST /api/activity/archive
```

**Body:**

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

Or pass specific IDs:

```json
{
    "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](../account/trash.md).

### List Trash

```http
GET /api/trash
```

**Query Parameters:**

| Parameter | Type   | Description                                  |
| --------- | ------ | -------------------------------------------- |
| `type`    | string | Filter: `all`, `project`, `dataset`, `model` |
| `page`    | int    | Page number (default: 1)                     |
| `limit`   | int    | Items per page (default: 50, max: 200)       |
| `owner`   | string | Workspace owner username                     |

### Restore Item

```http
POST /api/trash
```

**Body:**

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

### Permanently Delete Item

```http
DELETE /api/trash
```

**Body:**

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

!!! warning "Irreversible"

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

### Empty Trash

```http
DELETE /api/trash/empty
```

Permanently deletes all items in trash.

!!! note "Authentication"

    `DELETE /api/trash/empty` accepts API-key authentication and permanently deletes every item in the selected account or workspace trash.

---

## Billing API

Check your credit balance, plan usage, and transaction history. See [Billing documentation](../account/billing.md).

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

!!! note "Currency Units"

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

### Get Balance

```http
GET /api/billing/balance
```

**Response:**

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

### Get Usage Summary

```http
GET /api/billing/usage-summary
```

Returns plan details, limits, and usage metrics.

### Get Transactions

```http
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.

!!! note "API-key access"

    `GET /api/storage` accepts API-key authentication. Use the [Settings > Profile](../account/settings.md#storage-usage) page for the same interactive breakdown.

### Get Storage Info

```http
GET /api/storage
```

**Query Parameters:**

| Parameter | Type    | Description                                                              |
| --------- | ------- | ------------------------------------------------------------------------ |
| `details` | boolean | Set to `true` to include `topItems` (largest datasets, models, exports). |
| `owner`   | string  | Workspace username.                                                      |

**Response:**

```json
{
    "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:

```http
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](../data/index.md).

### Get Signed Upload URL

```http
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:**

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

| Field         | Type   | Description                                          |
| ------------- | ------ | ---------------------------------------------------- |
| `assetType`   | string | Asset type: `models`, `datasets`, `images`, `videos` |
| `assetId`     | string | ID of the target asset                               |
| `filename`    | string | Original filename                                    |
| `contentType` | string | MIME type                                            |
| `totalBytes`  | int    | File size in bytes                                   |

**Response:**

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

### Complete Upload

```http
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:**

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

---

## Integrations API

Import datasets from third-party services. See [Integrations documentation](../integrations/index.md).

### Preview Roboflow Import

```http
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

```http
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](../account/api-keys.md).

### List API Keys

```http
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

```http
POST /api/api-keys
```

**Body:**

```json
{
    "name": "training-server"
}
```

### Delete API Key

```http
DELETE /api/api-keys
```

**Query Parameters:**

| Parameter | Type   | Description                  |
| --------- | ------ | ---------------------------- |
| `keyId`   | string | API key ID to revoke         |
| `owner`   | string | Optional workspace username. |

**Example:**

```bash
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](../account/teams.md).

### List Teams

```http
GET /api/teams
```

### Create Team

```http
POST /api/teams/create
```

**Body:**

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

### List Members

```http
GET /api/members
```

Returns members of the current workspace.

### Invite Member

```http
POST /api/members
```

**Body:**

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

!!! info "Member Roles"

    | 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.

### Update Member Role

```http
PATCH /api/members/{userId}
```

### Remove Member

```http
DELETE /api/members/{userId}
```

### Transfer Ownership

```http
POST /api/members/transfer-ownership
```

---

## Explore API

Search and browse public datasets and projects shared by the community. See [Explore documentation](../explore.md).

### Search Public Content

```http
GET /api/explore/search
```

**Query Parameters:**

| Parameter | Type    | Description                                                                                                               |
| --------- | ------- | ------------------------------------------------------------------------------------------------------------------------- |
| `q`       | string  | Search query                                                                                                              |
| `type`    | string  | Resource type: `all` (default), `projects`, `datasets`                                                                    |
| `sort`    | string  | Sort order: `newest` (default), `stars`, `oldest`, `name-asc`, `name-desc`, `count-desc`, `count-asc`                     |
| `offset`  | int     | Pagination offset (default: 0). Results return 20 items per page.                                                         |
| `task`    | string  | Optional: comma-separated YOLO task types to filter datasets (`detect`, `segment`, `semantic`, `classify`, `pose`, `obb`) |
| `author`  | string  | Optional owner username filter.                                                                                           |
| `starred` | boolean | Set `true` to return the authenticated caller's starred content; requires an API key.                                     |

### Sidebar Data

```http
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/settings.md).

### Account Summary

```http
GET /api/account/summary
```

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

### Get User by Username

```http
GET /api/users
```

**Query Parameters:**

| Parameter  | Type   | Description         |
| ---------- | ------ | ------------------- |
| `username` | string | Username to look up |

### Follow or Unfollow User

```http
PATCH /api/users
```

**Body:**

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

### Check Username Availability

```http
GET /api/username/check
```

**Query Parameters:**

| Parameter  | Type   | Description                                       |
| ---------- | ------ | ------------------------------------------------- |
| `username` | string | Username to check                                 |
| `suggest`  | bool   | Optional: `true` to include a suggestion if taken |

### Settings

```http
GET /api/settings
POST /api/settings
```

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

### Workspace Icon

```http
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

```bash
pip install "ultralytics>=8.4.104"
```

Verify installation:

```bash
yolo check
```

### Authentication

=== "CLI (Recommended)"

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

=== "Environment Variable"

    ```bash
    export ULTRALYTICS_API_KEY=YOUR_API_KEY
    ```

=== "In Code"

    ```python
    from ultralytics import settings

    settings.update({"api_key": "YOUR_API_KEY"})
    ```

### Using Platform Datasets

Reference datasets with `ul://` URIs:

```python
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:**

| Pattern                            | Description    |
| ---------------------------------- | -------------- |
| `ul://username/datasets/slug`      | Dataset        |
| `ul://username/project-name`       | Project        |
| `ul://username/project/model-name` | Specific model |
| `ul://ultralytics/yolo26/yolo26n`  | Official model |

### Pushing to Platform

Send results to a Platform project:

```python
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:**

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

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

**Run inference:**

```python
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:**

```python
# 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:**

```python
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:

```bash
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:

```bash
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:

```bash
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](https://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:

```python
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:

```text
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.
