Sessions – Testmo

The sessions namespace provides API methods to retrieve, create, update and delete exploratory test sessions for a project. 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 `/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

Parameters

Schema

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

Parameters

Schema

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

Parameters

Schema

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

Parameters

Schema

name string
New name for the session.

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 /projects/{project_id}/sessions

Request

Response

Examples

Status codes

POST /projects/{project_id}/sessions

Request

Response

Examples

Status codes

GET /sessions/{session_id}

Request

Response

Examples

Status codes

PATCH /sessions/{session_id}

Request

Response

Examples

Status codes

DELETE /sessions/{session_id}

Response

Status codes

GET `/projects/{project_id}/sessions`

POST `/projects/{project_id}/sessions`

GET `/sessions/{session_id}`

PATCH `/sessions/{session_id}`

DELETE `/sessions/{session_id}`