Skip to main content

Runs

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

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 (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

Parameters
Schema

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.
 

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.
 

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."
  },
  "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

Parameters
Schema

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)

PATCH /runs/{run_id}

Updates a run. Only the fields provided in the request body are changed.

run_id id required
ID of the run to update.
 

Request

Parameters
Schema

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
Whether the run should include all test cases in the project.
 

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.
 

tags array
Array of tag strings to apply to the run.
  

{
  "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."
  },
  "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)

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)

Was this article helpful?