The runs namespace provides API methods to retrieve, create, update
and delete manual test runs for a project. The following endpoints are available:
-
GET
projects/{project_id}/runs -
POST
projects/{project_id}/runs -
GET
runs/{run_id} -
PATCH
runs/{run_id} -
PATCH
projects/{project_id}/runs/{run_id} -
DELETE
runs/{run_id} -
GET
projects/{project_id}/configs -
GET
projects/{project_id}/states -
GET
runs/{run_id}/tests
GET /projects/{project_id}/runs
Returns all runs for a project.
This method uses pagination so you might need to request additional pages to retrieve all runs.
project_id id required
ID of the project.
Request
page integer
Number of page to return (default: first page).
per_page integer
Maximum number of runs to return (supported: 15,
25, 50, 100; default:
100).
sort string
Sort field for the list of runs (supported: runs:created_at,
runs:closed_at; default: runs:created_at).
order string
Sort order (supported: asc, desc; default:
desc).
name string
Filter runs by name (partial match).
is_closed boolean
Limit results to active (false) or closed (true)
runs only.
milestone_id string
Comma-separated list of milestone IDs to filter by.
config_id string
Comma-separated list of configuration IDs to filter by.
state_id string
Comma-separated list of workflow state IDs to filter by.
tags string
Comma-separated list of tag names to filter by.
created_after string
Limit results to runs created after this date/time (ISO 8601, UTC).
created_before string
Limit results to runs created before this date/time (ISO 8601, UTC).
created_by string
Comma-separated list of user IDs to filter by creator.
closed_after string
Limit results to runs closed after this date/time (ISO 8601, UTC).
closed_before string
Limit results to runs closed before this date/time (ISO 8601, UTC).
expands string
Comma-separated list of expands to return.
{
"page": {
"type": "integer",
"format": "int64",
"description": "Number of page to return (default: first page)."
},
"per_page": {
"type": "integer",
"format": "int64",
"enum": [15, 25, 50, 100],
"description": "Maximum number of items to return per page (default: 100)."
},
"sort": {
"type": "string",
"enum": ["runs:created_at", "runs:closed_at"],
"default": "runs:created_at",
"description": "Sort field for the list of runs."
},
"order": {
"type": "string",
"enum": ["asc", "desc"],
"default": "desc",
"description": "Sort order (ascending or descending)."
},
"name": {
"type": "string",
"description": "Filter runs by name (partial match)."
},
"is_closed": {
"type": "boolean",
"description": "Limit results to active (false) or closed (true) runs only."
},
"milestone_id": {
"type": "string",
"description": "Comma-separated list of milestone IDs to filter by."
},
"config_id": {
"type": "string",
"description": "Comma-separated list of configuration IDs to filter by."
},
"state_id": {
"type": "string",
"description": "Comma-separated list of workflow state IDs to filter by."
},
"tags": {
"type": "string",
"description": "Comma-separated list of tag names to filter by."
},
"created_after": {
"type": "string",
"format": "date-time",
"description": "Limit results to runs created after this date/time (ISO 8601, UTC)."
},
"created_before": {
"type": "string",
"format": "date-time",
"description": "Limit results to runs created before this date/time (ISO 8601, UTC)."
},
"created_by": {
"type": "string",
"description": "Comma-separated list of user IDs to filter by creator."
},
"closed_after": {
"type": "string",
"format": "date-time",
"description": "Limit results to runs closed after this date/time (ISO 8601, UTC)."
},
"closed_before": {
"type": "string",
"format": "date-time",
"description": "Limit results to runs closed before this date/time (ISO 8601, UTC)."
},
"expands": {
"type": "string",
"description": "Comma-separated list of expands to return (configs, issues, milestones, states, statuses, users)."
}
}
This method supports the following expands so you can automatically include additional information for referenced objects:
-
configs -
issues -
milestones -
states -
statuses -
users
Response
GET /api/v1/projects/1/runs
200 OK
{
"page": 1,
"prev_page": null,
"next_page": 2,
"last_page": 2,
"per_page": 100,
"total": 150,
"result": [
{
"id": 1,
"project_id": 1,
"name": "Regression Run — v2.0",
"config_id": null,
"milestone_id": 5,
"state_id": 1,
"forecast": null,
"forecast_completed": null,
"elapsed": null,
"include_all": true,
"is_started": true,
"is_closed": false,
"issues": [],
"links": [],
"tags": [],
"untested_count": 80,
"status1_count": 15,
"status2_count": 5,
"status3_count": 0,
..
"success_count": 15,
"failure_count": 5,
"completed_count": 20,
"total_count": 100,
"started_at": "2025-09-20T09:00:00.000000Z",
"created_at": "2025-09-20T08:55:00.000000Z",
"created_by": 1,
"updated_at": null,
"updated_by": null,
"closed_at": null,
"closed_by": null
},
..
],
"expands": {}
}
Examples
// Get all runs for a project
GET /api/v1/projects/1/runs
// Filter by name (partial match)
GET /api/v1/projects/1/runs?name=regression
// Get active runs only
GET /api/v1/projects/1/runs?is_closed=false
// Get closed runs ordered by close date
GET /api/v1/projects/1/runs?is_closed=true&sort=runs:closed_at
// Filter by milestone
GET /api/v1/projects/1/runs?milestone_id=5
// Filter by creation date
GET /api/v1/projects/1/runs?created_after=2025-09-01T00:00:00Z
// Include configs and user expands
GET /api/v1/projects/1/runs?expands=configs,users
// Paginate through results
GET /api/v1/projects/1/runs?page=2&per_page=50
Status codes
200 401 403 422
429 (details)
POST /projects/{project_id}/runs
Creates a new manual test run in the specified project.
project_id id required
ID of the project.
Request
name string required
The name of the run.
state_id integer required
A valid workflow state ID for the run. Use
GET /projects/{project_id}/states
to retrieve available states.
include_all boolean required
When true, the run includes all test cases in the project.
When false, specific cases must be provided via
cases.
milestone_id integer
ID of the milestone to associate with this run.
config_id integer
ID of the configuration to associate with this run. Use
GET /projects/{project_id}/configs
to retrieve available configurations.
cases array
Array of case IDs to include in the run. Required when
include_all is false. Each case ID can appear only once. A duplicate returns 422 under cases, for example: The case_ids field contains the duplicate case ID 101. Each case can only be added to a run once.
case_ids array
Alias for cases — an array of case IDs to include in
the run. If both are supplied, cases takes precedence.
When cases are provided without include_all, the run
defaults to including only the specified cases (include_all
is treated as false).
origin_id integer
ID of an existing run to clone cases from.
note string
A short note for the run (max 80 characters).
docs string
Description or body text for the run.
issues array
Array of issues to link to the run. Each item is either an existing issue ID, which must belong to the project and must not be repeated, or an issue object with display_id, integration_id and an optional connection_project_id. Issue objects are matched to existing issues, and a new issue is created if there is no match. The array accepts up to 100 items.
tags array
Array of tag strings to apply to the run.
assign boolean
When true, automatically assigns the run tests to the
creating user.
{
"name": {
"type": "string",
"description": "Name of the run (required)."
},
"state_id": {
"type": "integer",
"format": "int64",
"description": "A valid workflow state ID for the run (required)."
},
"include_all": {
"type": "boolean",
"description": "When true, includes all project test cases. When false, use cases to specify which cases to include (required)."
},
"milestone_id": {
"type": "integer",
"format": "int64",
"nullable": true,
"description": "ID of the milestone to associate with this run."
},
"config_id": {
"type": "integer",
"format": "int64",
"nullable": true,
"description": "ID of the configuration to associate with this run."
},
"cases": {
"type": "array",
"items": { "type": "integer", "format": "int64" },
"description": "Array of case IDs to include. Required when include_all is false."
},
"case_ids": {
"type": "array",
"items": { "type": "integer", "format": "int64" },
"description": "Alias for cases. If both are supplied, cases takes precedence. Providing cases without include_all defaults include_all to false."
},
"origin_id": {
"type": "integer",
"format": "int64",
"nullable": true,
"description": "ID of an existing run to clone cases from."
},
"note": {
"type": "string",
"maxLength": 80,
"description": "Short note for the run."
},
"docs": {
"type": "string",
"description": "Description or body text."
},
"issues": {
"type": "array",
"description": "Array of issue objects to link."
},
"tags": {
"type": "array",
"items": { "type": "string" },
"description": "Array of tag strings."
},
"assign": {
"type": "boolean",
"description": "When true, automatically assigns run tests to the creating user."
}
}
Example
POST /api/v1/projects/1/runs
{
"name": "Regression Run — v2.1",
"state_id": 1,
"include_all": true,
"milestone_id": 5,
"tags": ["regression", "v2.1"]
}
201 Created
{
"result": {
"id": 87,
"project_id": 1,
"name": "Regression Run — v2.1",
"config_id": null,
"milestone_id": 5,
"state_id": 1,
"forecast": null,
"forecast_completed": null,
"elapsed": null,
"include_all": true,
"is_started": false,
"is_closed": false,
"issues": [],
"links": [],
"tags": [
{ "tag_id": 1, "name": "regression" },
{ "tag_id": 2, "name": "v2.1" }
],
"untested_count": 342,
"status1_count": 0,
..
"success_count": 0,
"failure_count": 0,
"completed_count": 0,
"total_count": 342,
"started_at": null,
"created_at": "2025-09-24T10:00:00.000000Z",
"created_by": 1,
"updated_at": null,
"updated_by": null,
"closed_at": null,
"closed_by": null
},
"expands": {}
}
Status codes
201 401 403 422
429 (details)
GET /runs/{run_id}
Returns a single run.
run_id id required
ID of the run.
Request
expands string
Comma-separated list of expands to return.
{
"expands": {
"type": "string",
"description": "Comma-separated list of expands to return (configs, issues, milestones, states, statuses, users)."
}
}
This method supports the following expands so you can automatically include additional information for referenced objects:
-
configs -
issues -
milestones -
states -
statuses -
users
Response
GET /api/v1/runs/1
200 OK
{
"result": {
"id": 1,
"project_id": 1,
"name": "Regression Run — v2.0",
"config_id": null,
"milestone_id": 5,
"state_id": 1,
"forecast": null,
"forecast_completed": null,
"elapsed": null,
"include_all": true,
"is_started": true,
"is_closed": false,
"issues": [],
"links": [],
"tags": [],
"untested_count": 80,
"status1_count": 15,
"status2_count": 5,
"status3_count": 0,
..
"success_count": 15,
"failure_count": 5,
"completed_count": 20,
"total_count": 100,
"started_at": "2025-09-20T09:00:00.000000Z",
"created_at": "2025-09-20T08:55:00.000000Z",
"created_by": 1,
"updated_at": null,
"updated_by": null,
"closed_at": null,
"closed_by": null
},
"expands": {}
}
Examples
// Get run with ID 1
GET /api/v1/runs/1
// Include config, milestone and user expands
GET /api/v1/runs/1?expands=configs,milestones,users
Status codes
200 401 403 404
429 (details)
GET /runs/{run_id}/tests
Lists the tests in a run. A test is a case that has been added to the run. The list includes tests that have no results yet.
Use the test_id value of each item as the test ID when you record a result. case_id is the repository case the test was created from. It is not a test ID.
Filter values must be positive whole numbers, separated by commas. An empty value, a value that is not a positive whole number, or an array form such as status_id[]=1 returns 422. Unknown query parameters are ignored. There are no date filters.
run_id id required
ID of the run.
Request
page integer
Page number. A page number past the last page returns the last page.
per_page integer
Number of items per page.
sort string
Sort column. Only run_tests:id is supported.
order string
Sort direction: asc or desc.
test_id array
Comma-separated run test IDs. Use the test_id value from this list.
case_id array
Comma-separated repository case IDs.
status_id array
Comma-separated status IDs.
assignee_id array
Comma-separated user IDs of the assignees.
folder_id array
Comma-separated folder IDs. Matches the folder of each test's case.
expands array
Comma-separated list of cases, folders, statuses and users. Adds the related objects to the expands field of the response. The IDs are returned in each item either way.
{
"page": {
"type": "integer"
},
"per_page": {
"type": "integer"
},
"sort": {
"type": "string",
"enum": [
"run_tests:id"
]
},
"order": {
"type": "string",
"enum": [
"asc",
"desc"
]
},
"test_id": {
"type": "array",
"items": {
"type": "integer"
}
},
"case_id": {
"type": "array",
"items": {
"type": "integer"
}
},
"status_id": {
"type": "array",
"items": {
"type": "integer"
}
},
"assignee_id": {
"type": "array",
"items": {
"type": "integer"
}
},
"folder_id": {
"type": "array",
"items": {
"type": "integer"
}
},
"expands": {
"type": "array",
"items": {
"type": "string",
"enum": [
"cases",
"folders",
"statuses",
"users"
]
}
}
}
Response
GET /api/v1/runs/87/tests?status_id=1,2
200 OK
{
"page": 1,
"prev_page": null,
"next_page": 2,
"last_page": 2,
"per_page": 2,
"total": 3,
"result": [
{
"id": 501,
"test_id": 501,
"run_id": 87,
"case_id": 101,
"folder_id": 12,
"status_id": 1,
"assignee_id": null,
"elapsed": null,
"is_closed": false
},
{
"id": 502,
"test_id": 502,
"run_id": 87,
"case_id": 102,
"folder_id": 12,
"status_id": 2,
"assignee_id": 1,
"elapsed": 35,
"is_closed": false
}
],
"expands": {}
}
Examples
// List the tests in run 87 with status 1 or 2
GET /api/v1/runs/87/tests?status_id=1,2
Status codes
200 401 403 404
422 429 (details)
PATCH /runs/{run_id}
Updates a run. Only the fields provided in the request body are changed.
Note: An update that includes neither case_ids, cases nor include_all no longer changes the run's case selection. Earlier versions could clear the selection in that case, so check any integration that sends partial updates. Unknown fields are ignored, except on a request that closes the run, which returns 422.
run_id id required
ID of the run to update.
Request
name string
New name for the run.
state_id integer
A valid workflow state ID.
milestone_id integer
ID of the milestone to associate with the run.
config_id integer
ID of the configuration to associate with the run.
include_all boolean
Set to true to select every case in the project and ignore case_ids. Set to false with case_ids to select only those cases, or set to false on its own to clear the selection. Leave the field out to keep the current selection. null returns 422.
cases array
Array of case IDs the run should include. Providing this without
include_all sets include_all to
false so the run includes only the specified cases. An empty array clears the selection. A value that is not an array returns 422, and sending both case_ids and cases in one request returns 422.
case_ids array
Alias for cases. If both are supplied, cases
takes precedence.
note string
Short note for the run (max 80 characters).
docs string
Description or body text.
issues array
Array of issues to link to the run. This replaces the run's existing issue links, so send an empty array to remove all of them. Items can be issue IDs or issue objects, as described for POST /projects/{project_id}/runs. The array accepts up to 100 items.
tags array
Array of tag strings to apply to the run.
is_closed boolean
Set to true to close the run. Closing cannot be undone. If the request also contains a field this endpoint does not accept, the request returns 422 and the run is not closed. false returns 422, because re-opening a closed run is not supported.
{
"name": {
"type": "string",
"description": "New name for the run."
},
"state_id": {
"type": "integer",
"format": "int64",
"description": "A valid workflow state ID."
},
"milestone_id": {
"type": "integer",
"format": "int64",
"nullable": true,
"description": "ID of the milestone to associate with the run."
},
"config_id": {
"type": "integer",
"format": "int64",
"nullable": true,
"description": "ID of the configuration to associate with the run."
},
"include_all": {
"type": "boolean",
"description": "Whether the run should include all test cases in the project."
},
"cases": {
"type": "array",
"items": { "type": "integer", "format": "int64" },
"description": "Array of case IDs the run should include. Providing this without include_all defaults include_all to false."
},
"case_ids": {
"type": "array",
"items": { "type": "integer", "format": "int64" },
"description": "Alias for cases. If both are supplied, cases takes precedence."
},
"note": {
"type": "string",
"maxLength": 80,
"description": "Short note for the run."
},
"docs": {
"type": "string",
"description": "Description or body text."
},
"issues": {
"type": "array",
"description": "Array of issue objects to link."
},
"tags": {
"type": "array",
"items": { "type": "string" },
"description": "Array of tag strings."
}
}
Example
PATCH /api/v1/runs/87
{
"name": "Regression Run — v2.1 (updated)",
"milestone_id": 6
}
200 OK
{
"result": {
"id": 87,
"project_id": 1,
"name": "Regression Run — v2.1 (updated)",
"config_id": null,
"milestone_id": 6,
"state_id": 1,
..
"updated_at": "2025-09-25T08:30:00.000000Z",
"updated_by": 1,
..
},
"expands": {}
}
Status codes
200 401 403 404
422 429 (details)
PATCH /projects/{project_id}/runs/{run_id}
Updates a run within the scope of a specific project. This behaves exactly like
PATCH /runs/{run_id} and accepts the same
request body, but additionally verifies that the run belongs to the given project.
If the run does not belong to the project, the request returns
404.
Note: The case selection rules, the issues behaviour and the is_closed rule are the same as for PATCH /runs/{run_id}.
project_id id required
ID of the project the run belongs to.
run_id id required
ID of the run to update. Must belong to project_id, otherwise
404 is returned.
Request
The request body is identical to
PATCH /runs/{run_id} — name,
state_id, milestone_id, config_id,
include_all, cases (or its alias
case_ids), note, docs,
issues and tags. Only the fields provided are changed.
Example
PATCH /api/v1/projects/1/runs/87
{
"name": "Regression Run — v2.1 (updated)",
"case_ids": [101, 102, 103]
}
200 OK
{
"result": {
"id": 87,
"project_id": 1,
"name": "Regression Run — v2.1 (updated)",
..
"include_all": false,
..
"updated_at": "2025-09-25T08:30:00.000000Z",
"updated_by": 1,
..
},
"expands": {}
}
Status codes
200 401 403 404
422 429 (details)
DELETE /runs/{run_id}
Deletes a run.
run_id id required
ID of the run to delete.
Returns a 204 no content response.
Example
DELETE /api/v1/runs/87
204 No Content
Status codes
204 401 403 404
429 (details)
GET /projects/{project_id}/configs
Returns the list of configurations for the specified project. Configurations represent test environments or platforms (e.g. "Chrome", "Firefox", "iOS"). Use this endpoint to retrieve valid configuration IDs for use when creating or filtering runs.
project_id id required
ID of the project.
Response
GET /api/v1/projects/1/configs
200 OK
{
"result": [
{
"id": 1,
"name": "Chrome"
},
{
"id": 2,
"name": "Firefox"
},
{
"id": 3,
"name": "Safari"
}
]
}
Status codes
200 401 403 404
429 (details)
GET /projects/{project_id}/states
Returns the list of workflow states for runs in the specified project. Use this endpoint to retrieve valid state IDs for use when creating or filtering runs.
project_id id required
ID of the project.
Response
GET /api/v1/projects/1/states
200 OK
{
"result": [
{
"id": 1,
"name": "Active",
"is_default": true
},
{
"id": 2,
"name": "In Review",
"is_default": false
},
{
"id": 3,
"name": "Approved",
"is_default": false
}
]
}
Status codes
200 401 403 404
429 (details)