Links

Runs

The runs namespace provides API methods to retrieve all or specific runs for a project. This page covers the following API methods:

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

Parameters
Schema
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 (ascending or descending) (supported: asc, desc; default: desc)
closed_after string Limit result to runs closed after (in ISO8601 format and UTC time zone).
closed_before string Limit result to runs closed before (in ISO8601 format and UTC time zone).
config_id string Comma-separated list of configurations to filter by.
created_after string Limit result to runs created after (in ISO8601 format and UTC time zone).
created_before string Limit result to runs created before (in ISO8601 format and UTC time zone).
created_by string Comma-separated list of users to filter by.
is_closed boolean Limit result to active or closed runs only.
milestone_id string Comma-separated list of milestones to filter by.
state_id string Comma-separated list of workflow states to filter by.
tags string Comma-separated list of tags to filter by.
expands string Comma-separated list of expands to return.
"page": {
"type": "integer",
"format": "int64",
"description": "Number of page (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"
],
"description": "Sort field for the list of runs."
},
"order": {
"type": "string",
"enum": [
"asc",
"desc"
],
"description": "Sort order (ascending or descending)."
},
"closed_after": {
"type": "string",
"format": "date-time",
"description": "Limit result to runs closed after (in ISO8601 format and UTC time zone)."
},
"closed_before": {
"type": "string",
"format": "date-time",
"description": "Limit result to runs closed before (in ISO8601 format and UTC time zone)."
},
"config_id": {
"type": "string",
"description": "Comma-separated list of configurations to filter by."
},
"created_after": {
"type": "string",
"format": "date-time",
"description": "Limit result to runs created after (in ISO8601 format and UTC time zone)."
},
"created_before": {
"type": "string",
"format": "date-time",
"description": "Limit result to runs created before (in ISO8601 format and UTC time zone)."
},
"created_by": {
"type": "string",
"description": "Comma-separated list of users to filter by."
},
"is_closed": {
"type": "boolean",
"description": "Limit result to active or closed runs only."
},
"milestone_id": {
"type": "string",
"description": "Comma-separated list of milestones to filter by."
},
"state_id": {
"type": "string",
"description": "Comma-separated list of workflow states to filter by."
},
"tags": {
"type": "string",
"description": "Comma-separated list of tags to filter by."
},
"expands": {
"type": "string",
"description": "Comma-separated list of expands to return."
}
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": "Run 1",
..
"is_closed": false,
"untested_count": 100,
"status1_count": 0,
"status2_count": 0,
"status3_count": 0,
"status4_count": 0,
"status5_count": 0,
"status6_count": 0,
"status7_count": 0,
"status8_count": 0,
"status9_count": 0,
"status10_count": 0,
"status11_count": 0,
"status12_count": 0,
"status13_count": 0,
"status14_count": 0,
"status15_count": 0,
"status16_count": 0,
"status17_count": 0,
"status18_count": 0,
"status19_count": 0,
"status20_count": 0,
"status21_count": 0,
"status22_count": 0,
"status23_count": 0,
"status24_count": 0,
"success_count": 0,
"failure_count": 0,
"completed_count": 0,
"total_count": 100,
"created_at": "..",
"created_by": 2,
"updated_at": null,
"updated_by": null,
"closed_at": null,
"closed_by": null
},
{
"id": 2,
"project_id": 1,
"name": "Run 2",
..
"is_closed": true,
"untested_count": 75,
"status1_count": 20,
"status2_count": 5,
"status3_count": 0,
"status4_count": 0,
"status5_count": 0,
"status6_count": 0,
"status7_count": 0,
"status8_count": 0,
"status9_count": 0,
"status10_count": 0,
"status11_count": 0,
"status12_count": 0,
"status13_count": 0,
"status14_count": 0,
"status15_count": 0,
"status16_count": 0,
"status17_count": 0,
"status18_count": 0,
"status19_count": 0,
"status20_count": 0,
"status21_count": 0,
"status22_count": 0,
"status23_count": 0,
"status24_count": 0,
"success_count": 20,
"failure_count": 5,
"completed_count": 25,
"total_count": 100,
"created_at": "..",
"created_by": 2,
"updated_at": null,
"updated_by": null,
"closed_at": "..",
"closed_by": 1
},
..
],
"expands": {
..
}
}

Examples

// Get latest 100 runs for project with ID 5
GET /api/v1/projects/5/runs
// Get second result page (pagination)
GET /api/v1/projects/5/runs?page=2
// Get latest 100 active runs
GET /api/v1/projects/5/runs?is_closed=0
// Get latest 100 closed runs, ordered by close date
GET /api/v1/projects/5/runs?is_closed=1&sort=runs:closed_at
// Get latest runs created after a certain date & time
GET /api/v1/projects/5/runs?created_after=2023-02-15T00:00:00.000Z
// Get runs and include expands
GET /api/v1/projects/5/runs?expands=configs,issues,users

Status codes

200 400 401 403 422 (details)

GET /runs/{run_id}

Returns a single run.
run_id id required ID of the run to return.

Request

Parameters
Schema
expands string Comma-separated list of expands to return.
"expands": {
"type": "string",
"description": "Comma-separated list of expands to return."
}
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": "Run 1",
..
"is_closed": false,
"untested_count": 100,
"status1_count": 0,
"status2_count": 0,
"status3_count": 0,
"status4_count": 0,
"status5_count": 0,
"status6_count": 0,
"status7_count": 0,
"status8_count": 0,
"status9_count": 0,
"status10_count": 0,
"status11_count": 0,
"status12_count": 0,
"status13_count": 0,
"status14_count": 0,
"status15_count": 0,
"status16_count": 0,
"status17_count": 0,
"status18_count": 0,
"status19_count": 0,
"status20_count": 0,
"status21_count": 0,
"status22_count": 0,
"status23_count": 0,
"status24_count": 0,
"success_count": 0,
"failure_count": 0,
"completed_count": 0,
"total_count": 100,
"created_at": "..",
"created_by": 2,
"updated_at": null,
"updated_by": null,
"closed_at": null,
"closed_by": null
},
"expands": {
..
}
}

Examples

// Get the run with ID 5
GET /api/v1/runs/5
// Get a run and include expands
GET /api/v1/runs/1?expands=configs,issues,users

Status codes

200 400 401 403 404 422 (details)