Sessions

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

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 (ascending or descending) (supported: asc, desc; default: desc)

assignee_id string Comma-separated list of assignees to filter by.

closed_after string Limit result to sessions closed after (in ISO8601 format and UTC time zone).

closed_before string Limit result to sessions 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 sessions created after (in ISO8601 format and UTC time zone).

created_before string Limit result to sessions 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 sessions 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.

template_id string Comma-separated list of templates 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": [
        "sessions:created_at",
        "sessions:closed_at"
    ],
    "description": "Sort field for the list of sessions."
},
"order": {
    "type": "string",
    "enum": [
        "asc",
        "desc"
    ],
    "description": "Sort order (ascending or descending)."
},
"assignee_id": {
    "type": "string",
    "description": "Comma-separated list of assignees to filter by."
},
"closed_after": {
    "type": "string",
    "format": "date-time",
    "description": "Limit result to sessions closed after (in ISO8601 format and UTC time zone)."
},
"closed_before": {
    "type": "string",
    "format": "date-time",
    "description": "Limit result to sessions 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 sessions created after (in ISO8601 format and UTC time zone)."
},
"created_before": {
    "type": "string",
    "format": "date-time",
    "description": "Limit result to sessions 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 sessions 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."
},
"template_id": {
    "type": "string",
    "description": "Comma-separated list of templates 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
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": "Session 1",
            ..
            "is_closed": false,
            "untested_count": 0,
            "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": 1,
            "created_at": "..",
            "created_by": 2,
            "updated_at": null,
            "updated_by": null,
            "closed_at": null,
            "closed_by": null
        },
        {
            "id": 2,
            "project_id": 1,
            "name": "Session 2",
            ..
            "is_closed": true,
            "untested_count": 0,
            "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": 1,
            "total_count": 1,
            "created_at": "..",
            "created_by": 2,
            "updated_at": null,
            "updated_by": null,
            "closed_at": "..",
            "closed_by": 1
        },
        ..
    ],
    "expands": {
        ..
    }
}

Examples

// Get latest 100 sessions for project with ID 5
GET /api/v1/projects/5/sessions

// Get second result page (pagination)
GET /api/v1/projects/5/sessions?page=2

// Get latest 100 active sessions
GET /api/v1/projects/5/sessions?is_closed=0

// Get latest 100 closed sessions, ordered by close date
GET /api/v1/projects/5/sessions?is_closed=1&sort=sessions:closed_at

// Get latest sessions created after a certain date & time
GET /api/v1/projects/5/sessions?created_after=2023-02-15T00:00:00.000Z

// Get sessions and include expands
GET /api/v1/projects/5/sessions?expands=configs,issues,users

Status codes

200 400 401 403 422 (details)

GET `/sessions/{session_id}`

Returns a single session.

session_id id required ID of the session to return.

Request

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
field_values
issues
milestones
states
statuses
templates
users

Response

GET /api/v1/sessions/1

200 OK
{
    "result": {
        "id": 1,
        "project_id": 1,
        "name": "Session 1",
        ..
        "is_closed": false,
        "untested_count": 0,
        "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": 1,
        "created_at": "..",
        "created_by": 2,
        "updated_at": null,
        "updated_by": null,
        "closed_at": null,
        "closed_by": null
    },
    "expands": {
        ..
    }
}

Examples

// Get the session with ID 5
GET /api/v1/sessions/5

// Get a session and include expands
GET /api/v1/sessions/1?expands=configs,issues,users

Status codes

200 400 401 403 404 422 (details)

PreviousRuns NextUsers

Last updated 4 months ago

Was this helpful?