User Story Version Executions

User story version executions represent individual test runs of a user story by testers in a test cycle. Each execution records the outcome (e.g. passed, failed, blocked), who executed it, when, and on which device or browser.

Prerequisites: You need a product with User Stories and Exploratory Tests. Executions are created when testers run user stories as part of a test cycle.

What are User Story Version Executions?

When a tester executes a user story during an exploratory test, the system creates a user story version execution. Each execution includes:

• Status – Whether the story passed, failed, was blocked, or is still pending
• Comment – The tester’s notes (required when status is passed, failed, or blocked)
• Executed by – The tester’s screen name
• Device/browser – Device reports describing the environment used
• Test cycle – The test cycle and test environment where the execution took place

Use this API to list executions for your user stories, filter by user story or version, and inspect results for reporting or integrations (e.g. InteractSoftware).

List user story version executions

Returns a paginated list of user story version executions for the current customer. Results can be filtered by user story IDs or user story version IDs and ordered by creation time.

Endpoint: GET /user_story_version_executions

Query Parameters:

Example Request (all executions, newest first):

1curl -X GET "https://api.test.io/customer/v2/user_story_version_executions?order=desc&per_page=10" \
2  -H "Authorization: Token YOUR_API_TOKEN"

Example Request (filter by user stories):

1curl -X GET "https://api.test.io/customer/v2/user_story_version_executions?user_story_ids[]=1&user_story_ids[]=2&order=desc&per_page=10" \
2  -H "Authorization: Token YOUR_API_TOKEN"

Example Request (filter by user story version IDs):

1curl -X GET "https://api.test.io/customer/v2/user_story_version_executions?user_story_version_ids[]=5&user_story_version_ids[]=6&page=1&per_page=25" \
2  -H "Authorization: Token YOUR_API_TOKEN"

Response: 200 OK

Response attributes (top level):

User story version execution object attributes:

Status values:

• pending – Execution not yet completed
• passed – Tester confirmed the user story works as expected
• failed – Tester found that the user story does not work as expected
• blocked – Tester could not complete the user story (e.g. environment issue)
• cancelled – Execution was cancelled

Device report object (each item in device_reports):

Test cycle object:

Example Response:

1{
2  "meta": {
3    "record_count": 42
4  },
5  "user_story_version_executions": [
6    {
7      "id": 101,
8      "status": "passed",
9      "comment": "Verified all steps on checkout flow.",
10      "executed_by": "tester.screenname",
11      "device_reports": [
12        {
13          "id": 1,
14          "category": { "id": 1, "key": "desktop", "name": "Desktop" },
15          "vendor": { "id": 1, "name": "Apple" },
16          "operating_system": { "id": 1, "key": "macos", "name": "macOS" },
17          "operating_system_version": { "id": 1, "name": "14.0" },
18          "device": { "id": 1, "name": "MacBook Pro" },
19          "browsers": [{ "id": 1, "name": "Chrome" }]
20        }
21      ],
22      "test_cycle": {
23        "id": 5,
24        "title": "Regression Test – February 2025",
25        "test_environment": { "id": 1, "title": "Staging" }
26      },
27      "executed_at": "2025-02-05T10:30:00.000Z"
28    },
29    {
30      "id": 102,
31      "status": "failed",
32      "comment": "Add to cart button does not respond on mobile.",
33      "executed_by": "another.tester",
34      "device_reports": [],
35      "test_cycle": {
36        "id": 5,
37        "title": "Regression Test – February 2025",
38        "test_environment": { "id": 2, "title": "Production" }
39      },
40      "executed_at": "2025-02-05T11:15:00.000Z"
41    }
42  ]
43}

Usage tips

• Use user_story_ids[] when you want all executions for specific user stories (e.g. for a feature or product view).
• Use user_story_version_ids[] when you need executions for specific user story versions (e.g. tied to a test cycle or version snapshot).
• Use order=desc and per_page to fetch the most recent executions first and control page size.
• meta.record_count reflects the total matching the filters; use it with per_page to compute total pages or show “X of Y” in the UI.