The sessions namespace provides API methods to retrieve, create,
update and delete exploratory test sessions for a project. Sessions can also be created and updated in bulk, and the results (log entries) of a session can be listed, retrieved, created and updated. This page covers the
following API methods:
-
GET
projects/{project_id}/sessions -
POST
projects/{project_id}/sessions -
GET
sessions/{session_id} -
PATCH
sessions/{session_id} -
DELETE
sessions/{session_id} -
GET
sessions/{session_id}/results -
GET
sessions/{session_id}/results/{result_id} -
POST
sessions/{session_id}/results -
PATCH
sessions/{session_id}/results/{result_id} -
POST
projects/{project_id}/sessions/bulk -
PATCH
projects/{project_id}/sessions/bulk
GET /projects/{project_id}/sessions
Returns all sessions for a project.
This method uses pagination so you might need to request additional pages to retrieve all sessions.
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 sessions to return (supported: 15,
25, 50, 100; default:
100).
sort string
Sort field for the list of sessions (supported:
sessions:created_at, sessions:closed_at;
default: sessions:created_at).
order string
Sort order (supported: asc, desc; default:
desc).
name string
Filter sessions by name (partial match).
is_closed boolean
Limit results to active (false) or closed (true)
sessions 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.
template_id string
Comma-separated list of session template IDs to filter by.
assignee_id string
Comma-separated list of assignee user IDs to filter by.
tags string
Comma-separated list of tag names to filter by.
created_after string
Limit results to sessions created after this date/time (ISO 8601,
UTC).
created_before string
Limit results to sessions 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 sessions closed after this date/time (ISO 8601,
UTC).
closed_before string
Limit results to sessions 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": ["sessions:created_at", "sessions:closed_at"],
"default": "sessions:created_at",
"description": "Sort field for the list of sessions."
},
"order": {
"type": "string",
"enum": ["asc", "desc"],
"default": "desc",
"description": "Sort order (ascending or descending)."
},
"name": {
"type": "string",
"description": "Filter sessions by name (partial match)."
},
"is_closed": {
"type": "boolean",
"description": "Limit results to active (false) or closed (true) sessions 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."
},
"template_id": {
"type": "string",
"description": "Comma-separated list of session template IDs to filter by."
},
"assignee_id": {
"type": "string",
"description": "Comma-separated list of assignee user 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 sessions created after this date/time (ISO 8601, UTC)."
},
"created_before": {
"type": "string",
"format": "date-time",
"description": "Limit results to sessions 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 sessions closed after this date/time (ISO 8601, UTC)."
},
"closed_before": {
"type": "string",
"format": "date-time",
"description": "Limit results to sessions closed before this date/time (ISO 8601, UTC)."
},
"expands": {
"type": "string",
"description": "Comma-separated list of expands to return (configs, field_values, issues, milestones, states, statuses, templates, users)."
}
}
This method supports the following expands so you can automatically include additional information for referenced objects:
-
configs -
field_values -
issues -
milestones -
states -
statuses -
templates -
users
Response
GET /api/v1/projects/1/sessions
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": "Exploratory session — login flow",
..
"is_closed": false,
"untested_count": 0,
"status1_count": 0,
"status2_count": 0,
"status3_count": 0,
..
"success_count": 0,
"failure_count": 0,
"completed_count": 0,
"total_count": 1,
"created_at": "2025-09-20T09:00:00.000000Z",
"created_by": 2,
"updated_at": null,
"updated_by": null,
"closed_at": null,
"closed_by": null
},
..
],
"expands": {}
}
Examples
// Get all sessions for a project
GET /api/v1/projects/1/sessions
// Filter by name (partial match)
GET /api/v1/projects/1/sessions?name=login
// Get active sessions only
GET /api/v1/projects/1/sessions?is_closed=false
// Get closed sessions ordered by close date
GET /api/v1/projects/1/sessions?is_closed=true&sort=sessions:closed_at
// Filter by milestone
GET /api/v1/projects/1/sessions?milestone_id=5
// Filter by creation date
GET /api/v1/projects/1/sessions?created_after=2025-09-01T00:00:00Z
// Include configs and user expands
GET /api/v1/projects/1/sessions?expands=configs,users
// Paginate through results
GET /api/v1/projects/1/sessions?page=2&per_page=50
Status codes
200 401 403 404
422 429 (details)
POST /projects/{project_id}/sessions
Creates a new session in the specified project. Only name is required;
all other fields are optional.
project_id id required
ID of the project.
Request
name string required
Name of the session.
session_type_id integer
ID of the session template (session type). Must be an active template.
(template_id is also accepted; supplying both
session_type_id and template_id in the
same request is rejected with a 422.)
description string
Short summary shown at the top of the session (maximum 80 characters).
milestone_id integer
ID of the milestone to associate with the session. The milestone
must not be completed.
assignee_id integer
ID of the user the session is assigned to.
config_id integer
ID of the configuration to associate with the session.
estimate string
Time estimate for the session (for example 30m or
1h 30m).
tags array
Array of tag names to associate with the session.
custom_* mixed
Values for the session template's custom fields, each prefixed with
custom_ (for example custom_environment).
Custom field values are validated against the selected template.
Any field that is neither in the list above nor prefixed with
custom_ is rejected with a 422.
{
"name": {
"type": "string",
"description": "Name of the session (required)."
},
"session_type_id": {
"type": "integer",
"format": "int64",
"description": "ID of the session template (active only). template_id is also accepted; supplying both is rejected."
},
"description": {
"type": "string",
"maxLength": 80,
"description": "Short summary (max 80 chars)."
},
"milestone_id": {
"type": "integer",
"format": "int64",
"description": "ID of the milestone (must not be completed)."
},
"assignee_id": {
"type": "integer",
"format": "int64",
"description": "ID of the assignee user."
},
"config_id": {
"type": "integer",
"format": "int64",
"description": "ID of the configuration."
},
"estimate": {
"type": "string",
"description": "Time estimate (e.g. 30m, 1h 30m)."
},
"tags": {
"type": "array",
"items": { "type": "string" },
"description": "Array of tag names."
}
}
Response
POST /api/v1/projects/1/sessions
201 Created
{
"result": {
"id": 42,
"project_id": 1,
"name": "Exploratory session — checkout flow",
"is_closed": false,
"untested_count": 0,
"status1_count": 0,
"status2_count": 0,
"status3_count": 0,
"success_count": 0,
"failure_count": 0,
"completed_count": 0,
"total_count": 0,
"created_at": "2025-09-20T14:05:00.000000Z",
"created_by": 2,
"updated_at": null,
"updated_by": null,
"closed_at": null,
"closed_by": null
},
"expands": {}
}
Examples
// Create a session with a name only
POST /api/v1/projects/1/sessions
{
"name": "Exploratory session — checkout flow"
}
// Create a session with a template, milestone and assignee
POST /api/v1/projects/1/sessions
{
"name": "Exploratory session — checkout flow",
"session_type_id": 3,
"milestone_id": 5,
"assignee_id": 2,
"estimate": "1h 30m"
}
// Create a session and set a template custom field value
POST /api/v1/projects/1/sessions
{
"name": "Regression sweep",
"session_type_id": 3,
"custom_environment": "Staging"
}
Status codes
201 400 401 403
404 415 422 429 (details)
GET /sessions/{session_id}
Returns a single session.
session_id id required
ID of the session.
Request
expands string
Comma-separated list of expands to return.
{
"expands": {
"type": "string",
"description": "Comma-separated list of expands to return (configs, field_values, issues, milestones, states, statuses, templates, users)."
}
}
This method supports the following expands so you can automatically include additional information for referenced objects:
-
configs -
field_values -
issues -
milestones -
states -
statuses -
templates -
users
Response
GET /api/v1/sessions/1
200 OK
{
"result": {
"id": 1,
"project_id": 1,
"name": "Exploratory session — login flow",
..
"is_closed": false,
"untested_count": 0,
"status1_count": 0,
"status2_count": 0,
"status3_count": 0,
..
"success_count": 0,
"failure_count": 0,
"completed_count": 0,
"total_count": 1,
"created_at": "2025-09-20T09:00:00.000000Z",
"created_by": 2,
"updated_at": null,
"updated_by": null,
"closed_at": null,
"closed_by": null
},
"expands": {}
}
Examples
// Get session with ID 1
GET /api/v1/sessions/1
// Include configs, milestone and user expands
GET /api/v1/sessions/1?expands=configs,milestones,users
Status codes
200 401 403 404
429 (details)
PATCH /sessions/{session_id}
Updates an existing session. Only the fields provided in the request body are
changed; omitted fields are left untouched. The request body cannot be empty
unless it contains is_closed.
session_id id required
ID of the session to update.
Request
name string
New name for the session.
session_type_id integer
ID of the session template (session type). Must be an active template.
(template_id is also accepted; supplying both
session_type_id and template_id in the
same request is rejected with a 422.)
description string
Short summary shown at the top of the session (maximum 80 characters).
milestone_id integer
ID of the milestone to associate with the session. The milestone
must not be completed.
assignee_id integer
ID of the user the session is assigned to.
config_id integer
ID of the configuration to associate with the session.
estimate string
Time estimate for the session (for example 30m or
1h 30m).
is_closed boolean
Set to true to close the session, or false
to keep it open.
tags array
Array of tag names to associate with the session.
custom_* mixed
Values for the session template's custom fields, each prefixed with
custom_ (for example custom_environment).
Custom field values are validated against the session's template.
Any field that is neither in the list above nor prefixed with
custom_ is rejected with a 422.
{
"name": {
"type": "string",
"description": "New name for the session."
},
"session_type_id": {
"type": "integer",
"format": "int64",
"description": "ID of the session template (active only). template_id is also accepted; supplying both is rejected."
},
"description": {
"type": "string",
"maxLength": 80,
"description": "Short summary (max 80 chars)."
},
"milestone_id": {
"type": "integer",
"format": "int64",
"description": "ID of the milestone (must not be completed)."
},
"assignee_id": {
"type": "integer",
"format": "int64",
"description": "ID of the assignee user."
},
"config_id": {
"type": "integer",
"format": "int64",
"description": "ID of the configuration."
},
"estimate": {
"type": "string",
"description": "Time estimate (e.g. 30m, 1h 30m)."
},
"is_closed": {
"type": "boolean",
"description": "Close (true) or reopen (false) the session."
},
"tags": {
"type": "array",
"items": { "type": "string" },
"description": "Array of tag names."
}
}
Response
PATCH /api/v1/sessions/42
200 OK
{
"result": {
"id": 42,
"project_id": 1,
"name": "Exploratory session — checkout flow (v2)",
"is_closed": false,
"untested_count": 0,
"status1_count": 0,
"status2_count": 0,
"status3_count": 0,
"success_count": 0,
"failure_count": 0,
"completed_count": 0,
"total_count": 0,
"created_at": "2025-09-20T14:05:00.000000Z",
"created_by": 2,
"updated_at": "2025-09-20T15:20:00.000000Z",
"updated_by": 2,
"closed_at": null,
"closed_by": null
},
"expands": {}
}
Examples
// Rename a session
PATCH /api/v1/sessions/42
{
"name": "Exploratory session — checkout flow (v2)"
}
// Reassign and re-estimate a session
PATCH /api/v1/sessions/42
{
"assignee_id": 5,
"estimate": "2h"
}
// Close a session
PATCH /api/v1/sessions/42
{
"is_closed": true
}
Status codes
200 400 401 403
404 415 422 429 (details)
DELETE /sessions/{session_id}
Permanently deletes a session. This cannot be undone.
session_id id required
ID of the session to delete.
Response
DELETE /api/v1/sessions/42
204 No Content
Status codes
204 401 403 404
429 (details)
GET /sessions/{session_id}/results
Returns a paged list of the results (log entries) for a session, newest first by default. Soft-deleted results are not returned.
Filter with status_id, created_by, created_after and created_before. Entries without a status (notes) are excluded when status_id is used. Unknown query parameters, including the run result filters test_id, case_id and assignee_id, are ignored.
session_id id required
ID of the session.
Request
page integer
Page of results to return.
per_page integer
Number of results per page.
expands string
Comma-separated list of expands: issues, users, statuses. statuses includes only active statuses referenced by the returned results.
sort string
Sort field. Supported: session_results:created_at.
order string
Sort direction.
created_after string
Only results created after this point (ISO 8601, UTC). A date-only value is treated as midnight UTC.
created_before string
Only results created before this point (ISO 8601, UTC). A date-only value includes the whole day.
created_by string
Comma-separated list of user IDs.
status_id string
Comma-separated list of status IDs.
{
"expands": {
"type": "string",
"description": "Comma-separated list of expands: issues, users, statuses."
},
"created_after": {
"type": "string",
"format": "date-time"
},
"created_before": {
"type": "string",
"format": "date-time"
},
"created_by": {
"type": "string",
"description": "Comma-separated list of user IDs."
},
"status_id": {
"type": "string",
"description": "Comma-separated list of status IDs."
}
}
Response
GET /api/v1/sessions/1/results?status_id=3
200 OK
{
"page": 1,
"prev_page": null,
"next_page": null,
"last_page": 1,
"per_page": 25,
"total": 1,
"result": [
{
"id": 7,
"project_id": 1,
"session_id": 1,
"status_id": 3,
"note": "Checkout fails with an expired card",
"elapsed": 5400000000,
"issues": [
12,
13
],
"is_activity": true,
"created_at": "2025-09-20T09:30:00.000000Z",
"created_by": 2,
"updated_at": null,
"updated_by": null
}
],
"expands": {}
}
Examples
// Get the results of session 1
GET /api/v1/sessions/1/results
// Only results with status 3, expanding the statuses
GET /api/v1/sessions/1/results?status_id=3&expands=statuses
Status codes
200 401 403 404
422 429 (details)
GET /sessions/{session_id}/results/{result_id}
Returns a single result (log entry) in a session.
A result that belongs to a different session, or that has been deleted, returns 404. Only the expands query parameter is accepted; any other query parameter is rejected with 422.
session_id id required
ID of the session.
result_id id required
ID of the result.
Request
expands string
Comma-separated list of expands: issues, users, statuses.
{
"expands": {
"type": "string",
"description": "Comma-separated list of expands: issues, users, statuses."
}
}
Response
GET /api/v1/sessions/1/results/7
200 OK
{
"result": {
"id": 7,
"project_id": 1,
"session_id": 1,
"status_id": 3,
"note": "Checkout fails with an expired card",
"elapsed": 5400000000,
"issues": [
12,
13
],
"is_activity": true,
"created_at": "2025-09-20T09:30:00.000000Z",
"created_by": 2,
"updated_at": null,
"updated_by": null
},
"expands": {}
}
Examples
// Get result 7 in session 1
GET /api/v1/sessions/1/results/7
// Include the issues and users expands
GET /api/v1/sessions/1/results/7?expands=issues,users
Status codes
200 401 403 404
422 429 (details)
POST /sessions/{session_id}/results
Adds a result or a note to an open session. Send status_id to record an outcome; leave it out to add a note. Send the text as comment or note, not both. At least one of comment, status_id, elapsed or issues is required. The first entry starts the session and moves it to its in-progress workflow state. A closed session is refused, and issues from another project are rejected.
Fields other than those listed here, including custom_ fields, return 422 naming the field. Query parameters are ignored.
session_id id required
ID of the session.
Request
comment string
Text of the entry. Returned as note.
note string
Public alias for comment. Send either note or comment, not both.
status_id integer
ID of a status available for sessions. Leave it out to add a note.
elapsed integer
Time spent, in microseconds, or a timespan string such as 1h 30m.
issues array
IDs of existing issues in the same project. Integer IDs only; the issue object format used by run endpoints is rejected.
{
"comment": {
"type": "string",
"description": "Text of the entry. Returned as note."
},
"note": {
"type": "string",
"description": "Public alias for comment. Send either, not both."
},
"status_id": {
"type": "integer",
"format": "int32",
"description": "Status available for sessions. Omit to add a note."
},
"elapsed": {
"type": "integer",
"format": "int64",
"description": "Time spent in microseconds, or a timespan string."
},
"issues": {
"type": "array",
"items": {
"type": "integer",
"format": "int64"
},
"description": "Integer issue IDs in the same project."
}
}
Response
POST /api/v1/sessions/1/results
201 Created
{
"result": {
"id": 7,
"project_id": 1,
"session_id": 1,
"status_id": 3,
"note": "Checkout fails with an expired card",
"elapsed": 5400000000,
"issues": [
12,
13
],
"is_activity": true,
"created_at": "2025-09-20T09:30:00.000000Z",
"created_by": 2,
"updated_at": null,
"updated_by": null
}
}
Examples
// Add a result with a status, time spent and linked issues
POST /api/v1/sessions/1/results
{
"comment": "Checkout fails with an expired card",
"status_id": 3,
"elapsed": "1h 30m",
"issues": [12, 13]
}
// Add a note
POST /api/v1/sessions/1/results
{
"note": "Retested on staging"
}
Status codes
201 400 401 403
404 415 422 429 (details)
PATCH /sessions/{session_id}/results/{result_id}
Updates a result in a session. Fields you do not send keep their current value, and at least one field is required. Send the text as comment or note, not both. Editing a result on a closed session is refused. Results cannot be deleted through the API.
A result that belongs to a different session, or that has been deleted, returns 404. Fields other than those listed here, including custom_ fields, return 422 naming the field. Query parameters are ignored.
session_id id required
ID of the session.
result_id id required
ID of the result.
Request
comment string
Text of the entry. Returned as note.
note string
Public alias for comment. Send either note or comment, not both.
status_id integer
ID of a status available for sessions. Leave it out to add a note.
elapsed integer
Time spent, in microseconds, or a timespan string such as 1h 30m.
issues array
IDs of existing issues in the same project. Integer IDs only; the issue object format used by run endpoints is rejected.
{
"comment": {
"type": "string",
"description": "Text of the entry. Returned as note."
},
"note": {
"type": "string",
"description": "Public alias for comment. Send either, not both."
},
"status_id": {
"type": "integer",
"format": "int32",
"description": "Status available for sessions. Omit to add a note."
},
"elapsed": {
"type": "integer",
"format": "int64",
"description": "Time spent in microseconds, or a timespan string."
},
"issues": {
"type": "array",
"items": {
"type": "integer",
"format": "int64"
},
"description": "Integer issue IDs in the same project."
}
}
Response
PATCH /api/v1/sessions/1/results/7
200 OK
{
"result": {
"id": 7,
"project_id": 1,
"session_id": 1,
"status_id": 4,
"note": "Checkout fails with an expired card",
"elapsed": 5400000000,
"issues": [
12,
13,
14
],
"is_activity": true,
"created_at": "2025-09-20T09:30:00.000000Z",
"created_by": 2,
"updated_at": "2025-09-20T10:15:00.000000Z",
"updated_by": 2
}
}
Examples
// Change the status and link a third issue
PATCH /api/v1/sessions/1/results/7
{
"status_id": 4,
"issues": [12, 13, 14]
}
Status codes
200 400 401 403
404 415 422 429 (details)
POST /projects/{project_id}/sessions/bulk
Creates up to 100 sessions in a project in one request. Each item accepts the same fields as the single session create endpoint, including custom_ fields.
All items are validated before anything is written. If any item fails, the request returns 422 and no sessions are created. Errors are keyed by the index of the item, for example sessions.1.milestone_id. The items are written in a single transaction.
project_id id required
ID of the project.
Request
sessions array required
Sessions to create: 1 to 100 items. Each item is an object with the fields of the single session create endpoint. name is required for each item.
{
"sessions": {
"type": "array",
"minItems": 1,
"maxItems": 100,
"description": "Sessions to create. Each item accepts the fields of the single session create endpoint.",
"items": {
"type": "object"
}
}
}
Response
POST /api/v1/projects/1/sessions/bulk
201 Created
[
{
"id": 42,
"project_id": 1,
"name": "Login Flow Testing",
"is_closed": false,
"total_count": 0,
"created_at": "2025-09-20T14:05:00.000000Z",
"created_by": 2,
"updated_at": null,
"updated_by": null,
"closed_at": null,
"closed_by": null
},
{
"id": 43,
"project_id": 1,
"name": "Checkout Flow Testing",
"is_closed": false,
"total_count": 0,
"created_at": "2025-09-20T14:05:00.000000Z",
"created_by": 2,
"updated_at": null,
"updated_by": null,
"closed_at": null,
"closed_by": null
}
]
Examples
// Create two sessions
POST /api/v1/projects/1/sessions/bulk
{
"sessions": [
{"name": "Login Flow Testing", "description": "Testing the login and authentication flow", "milestone_id": 5, "assignee_id": 12, "tags": ["smoke"]},
{"name": "Checkout Flow Testing", "estimate": "45m"}
]
}
Status codes
201 400 401 403
404 415 422 429 (details)
PATCH /projects/{project_id}/sessions/bulk
Updates up to 100 sessions in a project in one request. Each item must include the session id, and the session must belong to the project in the path. Updates are selected by ID only; filter-based updates are not supported.
All items are validated before anything is written. If any item fails, the request returns 422 and no sessions are changed. Every failing item is reported in the same response, keyed by its index, for example sessions.1.name. An ID that is unknown or belongs to another project is reported under sessions.{index}.id. Sessions that are already closed refuse updates. Setting is_closed to false does not reopen a closed session. The items are written in a single transaction.
project_id id required
ID of the project.
Request
sessions array required
Sessions to update: 1 to 100 items. Each item must include id. Other fields are optional and are the same as the single session update endpoint.
{
"sessions": {
"type": "array",
"minItems": 1,
"maxItems": 100,
"description": "Sessions to update. Each item must include id.",
"items": {
"type": "object",
"required": [
"id"
]
}
}
}
Response
PATCH /api/v1/projects/1/sessions/bulk
200 OK
[
{
"id": 1,
"project_id": 1,
"name": "Updated login flow",
"is_closed": false,
"total_count": 1,
"created_at": "2025-09-20T14:05:00.000000Z",
"created_by": 2,
"updated_at": null,
"updated_by": null,
"closed_at": null,
"closed_by": null
},
{
"id": 2,
"project_id": 1,
"name": "Checkout Flow Testing",
"is_closed": true,
"total_count": 0,
"created_at": "2025-09-20T14:05:00.000000Z",
"created_by": 2,
"updated_at": null,
"updated_by": null,
"closed_at": "2025-09-20T16:00:00.000000Z",
"closed_by": 2
}
]
Examples
// Rename one session, then reassign it and close another
PATCH /api/v1/projects/1/sessions/bulk
{
"sessions": [
{"id": 1, "name": "Updated login flow", "assignee_id": 12},
{"id": 2, "is_closed": true}
]
}
Status codes
200 400 401 403
404 415 422 429 (details)