# Train a Model

Once a project has a generated dataset version, you can schedule a training job that produces a hosted model. The REST API exposes job creation, listing, and details.

For the full training-time experience — choosing a base model architecture, monitoring training, and consuming credits — see the product docs on [training a model](https://docs.roboflow.com/train/train-a-model).

## Create a Training Job

<mark style="color:green;">`POST`</mark> `/:workspace/:project/jobs`

**Headers**

| Name         | Value              |
| ------------ | ------------------ |
| Content-Type | `application/json` |

**Body**

<table><thead><tr><th width="180">Name</th><th width="140">Type</th><th>Description</th><th data-type="checkbox">Required</th></tr></thead><tbody><tr><td><code>version</code></td><td>integer</td><td>Dataset version to train on.</td><td>true</td></tr><tr><td><code>model_type</code></td><td>string</td><td>Architecture identifier (e.g. <code>rfdetr-nano</code>, <code>yolov8</code>, <code>yolov11</code>). Pass an invalid value to receive the full list back as an error.</td><td>true</td></tr><tr><td><code>checkpoint</code></td><td>string</td><td>Optional checkpoint to continue training from.</td><td>false</td></tr><tr><td><code>epochs</code></td><td>integer</td><td>Number of epochs.</td><td>false</td></tr><tr><td><code>speed</code></td><td>string</td><td><code>fast</code> (default) or <code>accurate</code>. <code>accurate</code> is a paid feature.</td><td>false</td></tr></tbody></table>

**Example Request**

```bash
curl -X POST "https://api.roboflow.com/my-workspace/my-detector/jobs?api_key=$ROBOFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "version": 3,
    "model_type": "rfdetr-nano",
    "epochs": 100
  }'
```

**Response**

```json
{
  "jobId": "job_abc123",
  "status": "queued",
  "version": 3,
  "createdAt": "2026-05-01T17:05:33.000Z"
}
```

Training runs asynchronously. Poll the job to check status, or watch the version's `model` field for the trained model to appear.

Required scope: `version:train`.

## List Training Jobs

<mark style="color:green;">`GET`</mark> `/:workspace/:project/jobs`

```bash
curl "https://api.roboflow.com/my-workspace/my-detector/jobs?api_key=$ROBOFLOW_API_KEY"
```

**Response**

```json
{
  "jobs": [
    {
      "id": "job_abc123",
      "status": "training",
      "version": 3,
      "model_type": "rfdetr-nano",
      "createdAt": "2026-05-01T17:05:33.000Z",
      "progress": 0.42
    }
  ]
}
```

## Get a Training Job

<mark style="color:green;">`GET`</mark> `/:workspace/:project/jobs/:jobId`

```bash
curl "https://api.roboflow.com/my-workspace/my-detector/jobs/job_abc123?api_key=$ROBOFLOW_API_KEY"
```

Returns the same shape as the list endpoint, scoped to one job. `status` values you'll see: `queued`, `training`, `complete`, `failed`, `cancelled`.

## SDK and CLI equivalents

* SDK: `Project.train(...)` or `Version.train(...)`. See [Train a Model (SDK)](/developer/python-sdk/train-a-model.md).
* CLI: `roboflow train start ...`. See [Train a Model (CLI)](/developer/command-line-interface/train-a-model.md).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.roboflow.com/developer/rest-api/train-a-model.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.