# Launches API Source: https://docs.qualflare.com/docs/api/launches · Last updated: 2026-11-03 List and read the launches of a Qualflare project over the REST API and export a launch as a CTRF report, with filters, sorting and every launch field. The Launches API lets you list and read launches, and export one as a CTRF report, in a Qualflare project over REST at `https://api.qualflare.com/api/v1/launches`, authenticated with a project access token. | | | | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | **Base path** | `/api/v1/launches` and `/api/v1/launch/{launchSeq}` | | **Reads** | Any token. Token creator: (requires the Viewer role or higher in the project) | | **Uploads** | To create a launch, see [Upload results with the API](https://docs.qualflare.com/docs/api/collect) | | **Pages** | 10 launches per page, newest first, 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 launches list`, `qf launch get ` ([Launches commands](https://docs.qualflare.com/docs/cli/read-commands#launches)) | | **MCP** | `list_launches`, `get_launch` ([MCP server reference](https://docs.qualflare.com/docs/api/mcp-reference)) | The three endpoints, each with its own section below: | Endpoint | What it does | | ----------------------------------------- | ------------------------------------------------------------------------------------------------ | | **GET** `/api/v1/launches` | [List launches](https://docs.qualflare.com/docs/api/launches#list-launches) | | **GET** `/api/v1/launch/{launchSeq}` | [Get a launch](https://docs.qualflare.com/docs/api/launches#get-launch) | | **GET** `/api/v1/launch/{launchSeq}/ctrf` | [Export a launch as CTRF](https://docs.qualflare.com/docs/api/launches#export-ctrf) | ## List launches List launches returns one page of the project's launches, newest first unless you sort them. **GET** `/api/v1/launches` 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 branch names, up to 255 characters | | `milestone` | `query`, integer | | No | A milestone number | | `platforms` | `query`, string | | No | `android`, `ios`, `desktop`, `web` or `api`. Repeat it for more, up to 20 | | `automation` | `query`, string | | No | `automated` or `manual`. Repeat it for both | | `environments` | `query`, string | | No | An environment identifier. Repeat it for more, up to 50 | | `languages` | `query`, string | | No | A language identifier, such as `en`. Repeat it for more, up to 50 | | `sortBy` | `query`, string | `createdAt` | No | `seq`, `branch`, `platform`, `os`, `milestone`, `environment`, `language`, `browser`, `createdAt` or `updatedAt` | | `sortDir` | `query`, boolean | | No | `true` sorts in descending order, `false` in ascending order. Left out, the list comes newest first without `sortBy`, and in ascending order with it | ```bash curl -sS "https://api.qualflare.com/api/v1/launches?environments=staging" \ -H "Authorization: Bearer $QF_TOKEN" ``` Returns `200`: A page of launches: `items` and `paging`, 10 launches per page. * Filters combine: `platforms`, `automation`, `environments` and `languages` can repeat; `q` searches the branch. ## Get a launch Get a launch returns one launch by its number, with its result counts. **GET** `/api/v1/launch/{launchSeq}` Needs a project access token whose creator has the Viewer role or higher in the project. | Name | Type | Default | Required | Description | | ----------- | --------------- | ------- | -------- | ----------------- | | `launchSeq` | `path`, integer | | Yes | The launch number | ```bash curl -sS "https://api.qualflare.com/api/v1/launch/88" \ -H "Authorization: Bearer $QF_TOKEN" ``` Returns `200`: The launch. ```json { "seq": 88, "framework": "playwright", "platform": "web", "os": "linux", "branch": "main", "commit": "4f2c9a1e7b3d", "status": "failed", "automation": "automated", "totalCount": 120, "passedCount": 112, "failedCount": 5, "errorCount": 0, "skippedCount": 3, "timeoutCount": 0, "abortedCount": 0, "flakyCount": 2, "retryCount": 4, "properties": { "build": "1432" }, "environmentId": 3, "environmentName": "Staging", "languageName": "English", "languageUid": "en", "milestoneSeq": 3, "milestoneName": "v2.4 release", "browser": "chromium", "metadata": { "version": "0.4.0", "timestamp": "2026-10-28T09:12:31Z", "cliName": "qf" }, "aiSummary": "Five checkout tests failed on the coupon step; the rest passed.", "aiSummaryStatus": "completed", "createdAt": "2026-10-28T09:12:33Z", "updatedAt": "2026-10-28T09:14:02Z" } ``` * A number that isn't a launch of the project answers `404` with `launch not found`. ## Export a launch as CTRF Export a launch as CTRF returns one launch as a CTRF JSON report, with the same token access as reading the launch. **GET** `/api/v1/launch/{launchSeq}/ctrf` Needs a project access token whose creator has the Viewer role or higher in the project. | Name | Type | Default | Required | Description | | ----------- | --------------- | ------- | -------- | ----------------- | | `launchSeq` | `path`, integer | | Yes | The launch number | ```bash curl -sS "https://api.qualflare.com/api/v1/launch/88/ctrf" \ -H "Authorization: Bearer $QF_TOKEN" ``` Returns `200`: The launch as a CTRF JSON document. * `error`, `timeout` and `aborted` are written as `failed`, with the exact status in the result's `rawStatus` (or in its `extra` as `qualflare.status`, when the upload sent its own `rawStatus`), so uploading the export again to [`POST /api/v1/collect/ctrf`](https://docs.qualflare.com/docs/api/collect#collect-ctrf) restores them. * A launch with 20,000 or more case results (or 200,000 steps, 50,000 retry attempts or 20,000 attachments) answers `400` with `launch is too large to export as a single CTRF document`. * Public report URLs don't offer the export. See [Send CTRF reports](https://docs.qualflare.com/docs/cli/ctrf#export). ## Launch fields Every launch the Launches API returns has these fields: | Field | Type | Notes | | ------------------------------------------------------------------------------------------ | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `seq` | integer | The launch number in the project | | `framework` | string | The test framework, such as `playwright` | | `platform` | string | `android`, `ios`, `desktop`, `web` or `api` | | `os` | string | The operating system | | `branch`, `commit` | string | The Git branch and commit, or `null` | | `status` | string | `draft`, `passed`, `failed`, `skipped`, `error`, `pending`, `timeout` or `aborted` ([Launch statuses](https://docs.qualflare.com/docs/runs/launches#launch-statuses)) | | `automation` | string | `automated` or `manual` | | `totalCount` | integer | The case results in the launch | | `passedCount`, `failedCount`, `errorCount`, `skippedCount`, `timeoutCount`, `abortedCount` | integer | The case results with each status | | `flakyCount` | integer | The case results marked flaky | | `retryCount` | integer | The retries across all case results | | `properties` | object | The key-value properties sent with the upload | | `environmentId`, `environmentName` | integer, string | The launch's [environment](https://docs.qualflare.com/docs/runs/environments) | | `languageName`, `languageUid` | string | The launch's language, such as `English` and `en` | | `milestoneSeq`, `milestoneName` | integer, string | The launch's milestone, or `null` | | `browser` | string | The browser, or `null` | | `metadata` | object | What the uploading tool sent about itself, such as its `cliName` and `version` | | `testPlanSeq` | integer | The test plan the launch ran; left out when the launch has no test plan | | `aiSummary` | string | The AI summary of the launch, or `null` | | `aiSummaryStatus` | string | `pending`, `completed`, `failed`, `skipped`, `unavailable` or `disabled` | | `aiAnalysisContext` | object | On [Get a launch](https://docs.qualflare.com/docs/api/launches#get-launch) only, when `aiSummaryStatus` isn't `completed`: a `message` that says why, and `upgradeRequired` when the subscription is the reason. Left out otherwise | | `createdAt`, `updatedAt` | string | RFC 3339 timestamps | ## 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/launches` | `qf launches list`; `list_launches` | | **GET** `/api/v1/launch/{launchSeq}` | `qf launch get `; `get_launch` | | **GET** `/api/v1/launch/{launchSeq}/ctrf` | No qf command or MCP tool | ## Related * **Guides:** [Launches](https://docs.qualflare.com/docs/runs/launches) · [Share and export results](https://docs.qualflare.com/docs/runs/share-results) * **Reference:** [Upload results with the API](https://docs.qualflare.com/docs/api/collect) · [Errors and status codes](https://docs.qualflare.com/docs/api/errors) * **CLI/API:** [Qualflare API](https://docs.qualflare.com/docs/api)