# Milestones API Source: https://docs.qualflare.com/docs/api/milestones ยท Last updated: 2026-11-03 List and read the milestones of a Qualflare project over the REST API, with their result counts, a completion filter, sorting and every field. The Milestones API lets you list and read milestones in a Qualflare project over REST at `https://api.qualflare.com/api/v1/milestones`, authenticated with a project access token. | | | | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Base path** | `/api/v1/milestones` and `/api/v1/milestone/{seq}` | | **Reads** | Any token. Token creator: (requires the Viewer role or higher in the project). The API has no milestone writes | | **Pages** | 10 milestones per page, as `items` and `paging` | | **Limits** | [Rate limits and request sizes](https://docs.qualflare.com/docs/api/limits) | | **Errors** | [Errors and status codes](https://docs.qualflare.com/docs/api/errors) | | **CLI** | `qf milestones list`, `qf milestone get ` ([Milestones commands](https://docs.qualflare.com/docs/cli/read-commands#milestones)) | | **MCP** | `list_milestones`, `get_milestone` ([MCP server reference](https://docs.qualflare.com/docs/api/mcp-reference)) | | **Launches** | To link a launch to a milestone, send `milestone` with the upload ([Upload results with the API](https://docs.qualflare.com/docs/api/collect#launch-fields)) | The two endpoints, each with its own section below: | Endpoint | What it does | | --------------------------------- | -------------------------------------------------------------------------------------------- | | **GET** `/api/v1/milestones` | [List milestones](https://docs.qualflare.com/docs/api/milestones#list-milestones) | | **GET** `/api/v1/milestone/{seq}` | [Get a milestone](https://docs.qualflare.com/docs/api/milestones#get-milestone) | ## List milestones List milestones returns one page of the project's milestones with their result counts. **GET** `/api/v1/milestones` Needs a project access token whose creator has the Viewer role or higher in the project. | Name | Type | Default | Required | Description | | --------------- | ---------------- | ------- | -------- | --------------------------------------------------------- | | `page` | `query`, integer | `1` | No | Page number, 1 to 1,000 | | `q` | `query`, string | | No | Text to look for in milestone names, up to 255 characters | | `isCompleted[]` | `query`, boolean | | No | `false` for open milestones, `true` for completed ones | | `sortBy` | `query`, string | `seq` | No | `seq`, `name`, `duesAt`, `createdAt` or `updatedAt` | | `sortDir` | `query`, boolean | `false` | No | `true` sorts in descending order | ```bash curl -sS -g "https://api.qualflare.com/api/v1/milestones?isCompleted[]=false" \ -H "Authorization: Bearer $QF_TOKEN" ``` Returns `200`: A page of milestones: `items` and `paging`, 10 milestones per page. * `isCompleted[]=false` lists open milestones, and `isCompleted[]=true` completed ones. ## Get a milestone Get a milestone returns one milestone by its number and adds `launchCount` and `runCount`. **GET** `/api/v1/milestone/{seq}` Needs a project access token whose creator has the Viewer role or higher in the project. | Name | Type | Default | Required | Description | | ----- | --------------- | ------- | -------- | -------------------- | | `seq` | `path`, integer | | Yes | The milestone number | ```bash curl -sS "https://api.qualflare.com/api/v1/milestone/3" \ -H "Authorization: Bearer $QF_TOKEN" ``` Returns `200`: The milestone, with `launchCount` and `runCount`. ```json { "seq": 3, "name": "v2.4 release", "description": "Regression and smoke runs for the v2.4 release", "kind": "release", "isCompleted": false, "totalCount": 240, "passedCount": 226, "failedCount": 9, "errorCount": 1, "skippedCount": 4, "timeoutCount": 0, "abortedCount": 0, "assignees": [ "3f6c2b9e-8d41-4a7f-b2e5-6c1d9a0e7f34" ], "launchCount": 6, "runCount": 2, "duesAt": "2026-11-15T00:00:00Z", "completedAt": "2026-10-01T08:30:00Z", "createdAt": "2026-10-01T08:30:00Z", "updatedAt": "2026-10-28T09:14:02Z" } ``` * A number that isn't a milestone of the project answers `404` with `milestone not found`. ## Milestone fields Every milestone the Milestones API returns has these fields: | Field | Type | Notes | | -------------------------------------------------------------------------------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `seq` | integer | The milestone number in the project | | `name` | string | The milestone name | | `description` | string | Empty when the milestone has none | | `kind` | string | `cycle`, `feature`, `iteration`, `plan`, `release`, `sprint` or `version` | | `isCompleted` | boolean | `true` for a completed milestone | | `totalCount`, `passedCount`, `failedCount`, `errorCount`, `skippedCount`, `timeoutCount`, `abortedCount` | integer | The case results of the latest run of each suite in the milestone's launches ([milestone health](https://docs.qualflare.com/docs/test-management/milestones#how-milestone-health-is-calculated)) | | `assignees` | array of strings | The user IDs of the people assigned | | `launchCount`, `runCount` | integer | On get only: the launches linked to the milestone, and the suite runs the counts come from | | `duesAt` | string | The due date | | `completedAt` | string | Always a date, also for an open milestone | | `createdAt`, `updatedAt` | string | RFC 3339 timestamps | * `completedAt` always holds a date; read `isCompleted` to know whether the milestone is done. ## CLI and MCP equivalents The qf CLI and the MCP server run the same reads, so they return the same JSON: | REST | qf command and MCP tool | | --------------------------------- | ------------------------------------------------------ | | **GET** `/api/v1/milestones` | `qf milestones list`; `list_milestones` | | **GET** `/api/v1/milestone/{seq}` | `qf milestone get `; `get_milestone` | ## Related * **Guides:** [Milestones](https://docs.qualflare.com/docs/test-management/milestones) * **Reference:** [Launches API](https://docs.qualflare.com/docs/api/launches) * **CLI/API:** [Qualflare API](https://docs.qualflare.com/docs/api)