For the complete documentation index, see llms.txt. This page is also available as Markdown.

Model IDs

How model IDs are structured and how legacy project/version IDs resolve to models.

Every trained model has a model ID that identifies it when you deploy it, run inference, or select it in a Workflow model block. This page describes the current structure of model IDs, as well as how a previous (legacy) format of ID is still supported under some circumstances.

Model ID Structure

A model ID has the form {workspace}/{model-slug}. The first part is your Workspace URL slug. The second part, the model slug, identifies the model within the workspace and is built from four parts joined by hyphens:

{project}-{version}-{architecture}-t{n}
  • project: the URL slug of the project the model belongs to. Example: construction-safety-xpv3w.

  • version: the number of the dataset version the model was trained on. Example: 12.

  • architecture: the model architecture used for training. Example: rfdetr-small.

  • t{n}: a training counter for the version. The first training started on a version is t1, the second is t2, and so on.

For example, the second RF-DETR Small training on version 3 of a project with the URL slug construction-safety-xpv3w in the workspace my-workspace produces the model ID my-workspace/construction-safety-xpv3w-3-rfdetr-small-t2.

The model slug is assigned when a training starts, so you can see the ID a model will have while it is still training. Training counter suffixes are never reused: if a training fails or is cancelled, its number is skipped and the next training on the version gets the next one.

A Neural Architecture Search training produces many candidate models. NAS candidate model IDs look like other model IDs, but with a double hyphen and a 6-character hash appended (ex: my-workspace/construction-safety-xpv3w-3-rfdetr-nas-t1--9589f2). In the v2 trainings endpoints, a NAS training reports its modelType as rfdetr-nas-parent, while each of its candidate models reports rfdetr-nas.

Find a Model ID

You can look up the ID of any trained model in the web app, with the HTTP API, or with the Roboflow MCP Server.

Web App

Click "Models" in your project sidebar to open the Models page. Each model shows its ID next to the "ID:" label, with a "Copy Model ID" button next to it. The same ID and copy button appear on the model's detail view and in the models table on each version page.

HTTP API

List Project Models

Returns every model trained in a project. The url field of each entry is the model ID.

List models for a project

get

Returns every trained model in a project: models trained on a dataset version and models that are not tied to one, such as Neural Architecture Search results. Requires model:infer.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Path parameters
workspacestringRequired

Workspace URL slug.

projectstringRequired

Project URL slug.

Query parameters
groupstringOptional

Neural Architecture Search run ID. Returns only the models from that run, or an empty array when none match.

Example: pVYKOWUB6AUIVJMgPc7u-410-rfdetrNasGroup
Responses
200

Successful response.

application/json
urlstringOptional

Model ID to use for inference.

versionstringOptional

Dataset version the model was trained on. Not set for models that are not tied to a version.

taskTypestringOptional

Task the model performs (ex: object-detection).

modelTypestringOptional

Model architecture and size (ex: rfdetr-base).

namestringOptional

Model display name.

createdstring · date-timeOptional

Creation time.

nasFamilystring · nullableOptional

child for models found by Neural Architecture Search, null for the baseline. Neural Architecture Search models only.

groupstringOptional

Neural Architecture Search run ID, shared by every model from the run.

favoritedbooleanOptional

True when anyone in the workspace starred the model. Neural Architecture Search models only.

recommendedbooleanOptional

Present and true when the model is the recommended pick for at least one metric and hardware target.

get/{workspace}/{project}/models
GET /{workspace}/{project}/models HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
[
  {
    "url": "my-project/3",
    "version": "3",
    "train": {
      "status": "finished"
    },
    "taskType": "object-detection",
    "modelType": "rfdetr-base",
    "name": "My Model",
    "created": "2026-04-01T00:00:00.000Z",
    "metrics": {
      "map50": 91,
      "precision": 88,
      "recall": 85
    }
  }
]

List Trainings

Returns the trainings on one version. Each training lists the IDs of the models it produced in modelIds. On a legacy single-model version, the training id has the form {projectId}/{version}/training/0, and modelIds holds the version's legacy ID.

List training runs

get

Lists the trainings on a dataset version, each with the IDs of the models it produced. Requires version:read.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Path parameters
workspacestringRequired

Workspace URL slug.

projectstringRequired

Project URL slug.

versioninteger · min: 1Required

Dataset version number.

Responses
200

Successful response.

application/json
get/{workspace}/{project}/{version}/v2/trainings
GET /{workspace}/{project}/{version}/v2/trainings HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
  "trainings": [
    {
      "id": "0a1b2c3d4e5f67890abc",
      "versionId": "3",
      "status": "finished",
      "start": 1775001600000,
      "end": 1775005200000,
      "jobType": "fine-tune",
      "modelType": "rfdetr-small",
      "modelGroup": null,
      "modelIds": [
        "my-workspace/construction-safety-xpv3w-3-rfdetr-small-t2"
      ]
    }
  ]
}

Get a Training

Returns one training with its status, metrics, and each model's ID in models[].modelId. You can leave out trainingId when the version has only one training. If it has several, the request returns 409.

Get a training run

get

Returns one training's status, models, and metrics. Requires version:read.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Path parameters
workspacestringRequired

Workspace URL slug.

projectstringRequired

Project URL slug.

versioninteger · min: 1Required

Dataset version number.

Query parameters
trainingIdstringOptional

Training to return. Leave it out when the version has only one training.

Example: 0a1b2c3d4e5f67890abc
includeEpochsbooleanOptional

Send true to add the metrics for each epoch. Not supported on legacy single-model versions.

Default: false
Responses
200

Successful response.

application/json
trainingIdstring · nullableOptional

Training ID. A 20-character hex ID for a training on a version that can hold several. For a legacy single-model version, a path of the form {projectId}/{version}/training/0, where projectId is the project's internal ID. null when the version has no training.

versionIdstringOptional

Dataset version number.

statusstringOptional

Training status: initializing, queued, generating, training, running, mining (Neural Architecture Search is searching architectures), finished, failed, cancelled, or stopped. not_started when the version has no training.

Example: finished
exceptionstringOptional

Failure reason, up to 500 characters. Present only when the training failed.

startinteger · nullableOptional

Start time in milliseconds since the Unix epoch.

endinteger · nullableOptional

End time in milliseconds since the Unix epoch.

jobTypestringOptional

Kind of training: fine-tune, nas (Neural Architecture Search), fine-tune-multi-stage, external-upload, or unknown.

modelTypestringOptional

Architecture the training ran. A Neural Architecture Search training reports rfdetr-nas-parent.

externalUploadbooleanOptional

True when the model weights were uploaded instead of trained on Roboflow.

modelGroupstring · nullableOptional

Neural Architecture Search run ID, shared by every model from the run. null for other trainings.

modelCountintegerOptional

Models the training produced.

get/{workspace}/{project}/{version}/v2/trainings/get
GET /{workspace}/{project}/{version}/v2/trainings/get HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
  "trainingId": "0a1b2c3d4e5f67890abc",
  "versionId": "3",
  "status": "finished",
  "start": 1775001600000,
  "end": 1775005200000,
  "jobType": "fine-tune",
  "modelType": "rfdetr-small",
  "modelGroup": null,
  "modelCount": 1,
  "models": [
    {
      "modelId": "my-workspace/construction-safety-xpv3w-3-rfdetr-small-t2",
      "modelType": "rfdetr-small",
      "status": "finished",
      "metrics": {
        "map50": 91.2,
        "map5095": 64.1,
        "precision": 88.4,
        "recall": 85,
        "f1": 86.7,
        "f1ConfThresh": 0.42
      }
    }
  ]
}

MCP Server

The Roboflow MCP Server provides tools that return model IDs. models_list lists the trained models of one project (the workspace comes from the connection's credentials, and the project is passed as project_id) and returns each model's ID in its url field, with optional filtering by version or NAS run. trainings_get and trainings_list return the IDs of the models each training produced. Agents can pass these IDs to other tools, such as models_infer.

Legacy Model IDs

In the past, Roboflow dataset versions could only have one training run on them, so models used to be uniquely determined by an ID of the form {project}/{version}.

For example, construction-site-safety/3 used to refer to the model trained on version 3 of that project. The first part is the project URL slug, not the workspace, and the second part is the version number. This is the format older SDKs, code snippets, and Inference installations use (ex: model_id="construction-site-safety/3").

Because it is now possible to run more than one training on a dataset version, these legacy-format IDs are no longer preferred. If you try to use such IDs for new trainings launched after June 30th, 2026, they will resolve under-the-hood to the new style of ID.

How Legacy IDs Resolve

Legacy-format IDs keep working through aliases. When the first training started on a version completes successfully, Roboflow links the version's legacy {project}/{version} ID to the new model ID. Requests that use the legacy ID, including weights downloads from older Inference installations, resolve to that model automatically.

The alias is created only by the first training on a version and does not change afterward:

  • If the first training completes successfully, the legacy ID refers to that model permanently, even after you train more models on the same version. Reference later models by their own model IDs.

  • If the first training fails or is cancelled, no alias is created, and later trainings on the version do not create one.

A version without an alias can still be referenced by its legacy ID as long as it holds exactly one model. If it holds several models and has no alias, requests using the legacy ID fail because the reference is ambiguous, and you must use the model's own ID.

Legacy IDs exist for backwards compatibility. Prefer full model IDs in new integrations: they are unambiguous and work for every model on a version.

Last updated

Was this helpful?