API ReferenceDeveloper GuidesRecipesDocumentationCommunityAcademyPlatform
Developer Guides

Read manual execution evidence

Find a manual run. Read its saved cases, activity, and data-bound iterations.
Start an iteration timer. Stop it when you leave the row. Mark an iteration
without rerunning its steps.

1. Authenticate in a project

Use https://<tenant>.katalon.io with no trailing slash. Authenticate using HTTP
Basic with an empty username and a Katalon API key as the password. See
Authenticate with the v2 API.
Your key's user needs access to the project. Requires the TestRun:Read
permission. Send x-project-id on every request.
An optional x-account-id is an account UUID, not a numeric account ID; it
must match the project's owning account. An optional x-organization-id must
also match the project's parent organization.

Set KATALON_API_HOST, KATALON_PROJECT_ID, and KATALON_API_KEY from your
environment or secret store. Do not enable shell tracing. This Bash helper
passes credentials on standard input rather than curl's process arguments.
If a key contains " or \, escape those characters as \" and \\ for curl's
configuration format.

katalon_request() {
  : "${KATALON_API_KEY:?Missing API key}"
  printf 'user = ":%s"\n' "${KATALON_API_KEY}" |
  curl --config - --silent --show-error --fail-with-body \
    --header "x-project-id: ${KATALON_PROJECT_ID:?Missing project ID}" \
    "$@"
}

2. Find an existing manual run

Find manual executions
by the run's displayed order in this project. Replace 1 with that order:

katalon_request --get "${KATALON_API_HOST}/v2/manual-test/executions" \
  --data-urlencode 'query=order==1' \
  --data-urlencode 'pageToken=0' --data-urlencode 'size=10'

The response has items, totalItems, size, and nextPageToken, without a
data wrapper. In each item, id and executionId are the manual execution
ID. Save that value as MANUAL_EXECUTION_ID for the /executions/... paths.
Save the separate externalExecutionId as TEST_RUN_ID. Use it for the TestOps
run ID, not for the execution-local paths below. See
Know which ID is which.

Page tokens are zero-based page indexes written as strings. The default size
is 10; the maximum effective size is 50. nextPageToken is returned even on the
last page, so stop based on the item count and totalItems, not token presence.
No default sort order is guaranteed. You can request comma-separated entity
fields with sort, prefixing a field with - for descending order.

3. Read saved case occurrences and content

List execution-local test cases:

katalon_request "${KATALON_API_HOST}/v2/manual-test/executions/${MANUAL_EXECUTION_ID:?Missing manual execution ID}/test-cases"

This response is an array, not a page. Test cases run outside a suite are
not returned. Choose the top-level item's id as
EXECUTION_TEST_CASE_ID. Its nested testCase.id is the Test Management case ID,
not the occurrence ID. Nested testSuite.id is the Test Management suite ID.

Read saved content:

katalon_request "${KATALON_API_HOST}/v2/manual-test/executions/${MANUAL_EXECUTION_ID:?Missing manual execution ID}/test-cases/${EXECUTION_TEST_CASE_ID:?Missing occurrence ID}/content"

testCaseDetails describes the case version used in the run, and testCaseFlow
contains its saved steps when available. This is not the latest editable case.
testCaseDetails.testProject.id identifies the repository, not the project
header. A 409 with MANUAL_CONTENT_NOT_READY means the content is still being
prepared; use bounded retries with a delay. Do not retry unavailable content
indefinitely or substitute the latest editable case. When content is missing
but can be prepared, the GET can queue background preparation before returning
409.

4. Read run-level comments

Find activity evidence.
Use source type EXECUTION and TEST_RUN_ID for a run-level comment:

katalon_request --get "${KATALON_API_HOST}/v2/manual-test/activities" \
  --data-urlencode "query=sourceType==EXECUTION;sourceId==${TEST_RUN_ID:?Missing TestOps run ID};activityType==COMMENT" \
  --data-urlencode 'pageToken=0' --data-urlencode 'size=10'

If you already have a manual result's mtResultId, use
sourceType==TEST_CASE_RESULT and that mtResultId as sourceId. Do not use
the test-case ID.
For version audit of a case occurrence, the source type is EXECUTION_TEST_CASE
and sourceId is the occurrence ID. Always filter source type and ID together.
The returned activity does not include sourceType, so retain that context.

Activity data varies by activityType: comments can include attachment metadata,
step activity can include testStepId, and status activity can include
fromData and toData. Responses may contain additional fields. Handle comments,
names, screenshots, and other evidence as sensitive project information. The
activity list returns attachment metadata, not attachment bytes. These operations
do not write activity.

5. List materialized iterations

List iterations for a test case
by using its EXECUTION_TEST_CASE_ID from step 3:

katalon_request --get "${KATALON_API_HOST}/v2/manual-test/executions/${MANUAL_EXECUTION_ID:?Missing manual execution ID}/test-cases/${EXECUTION_TEST_CASE_ID:?Missing occurrence ID}/iterations" \
  --data-urlencode 'pageToken=0' --data-urlencode 'size=20'

You can filter by environmentId. A case without created iteration rows returns
an empty iterations array. Data-binding settings affect whether rows exist.
When you send environmentId, expansionPending: true means rows for that case
and environment are still pending. An empty list may be temporary. If you omit
environmentId, expansionPending is not an all-environments signal. A false
value does not prove that binding was not configured or that expansion completed.
Iteration lists default to 200 rows. The service clamps requested size to 1
through 200. Invalid or negative page tokens use page 0. The response returns
nextPageToken even on the last page. Stop after reading totalItems rows.

List iterations in a manual run
with the same page parameters:

katalon_request --get "${KATALON_API_HOST}/v2/manual-test/executions/${MANUAL_EXECUTION_ID:?Missing manual execution ID}/iterations" \
  --data-urlencode 'pageToken=0' --data-urlencode 'size=20'

In this response, totalExecutions counts bound iterations and unbound
case-environment pairs, not test cases. The cases summaries appear on the
first page. Use iteration progress
when you need those summaries without the iteration rows:

katalon_request "${KATALON_API_HOST}/v2/manual-test/executions/${MANUAL_EXECUTION_ID:?Missing manual execution ID}/iterations/progress"

Progress is execution-grain. It counts each unbound case-environment pair as
one execution, even when that pair has no iteration row.

6. Read one iteration and its result history

Save an iterations[].id value as ITERATION_ID. It is a UUID. Get the row with
rendered case steps by using
Get a manual iteration:

katalon_request --get "${KATALON_API_HOST}/v2/manual-test/iterations/${ITERATION_ID:?Missing iteration ID}" \
  --data-urlencode 'includeSteps=true'

Secret-sourced values are masked. A masked value looks like
{"ref":"PWD","secret":true}; it does not show the secret value.

Read current and superseded attempts with
Get an iteration's result history:

katalon_request "${KATALON_API_HOST}/v2/manual-test/iterations/${ITERATION_ID:?Missing iteration ID}/results"

The response lists the current result first, then older results from newest to
oldest. It also lists status audit entries from oldest to newest. Each result
keeps its own attachment metadata and defect links.

7. Time an iteration

Requires the TestRun:Update permission. Start the caller's timer with
Start an iteration timer:

katalon_request --request POST \
  "${KATALON_API_HOST}/v2/manual-test/iterations/${ITERATION_ID:?Missing iteration ID}/timer/start"

The request is idempotent. It pauses your timer on other rows for the same case
and environment. It leaves other callers' timers unchanged. The run must be open
to start a timer.

Use Stop an iteration timer
when you leave the row:

katalon_request --request POST \
  "${KATALON_API_HOST}/v2/manual-test/iterations/${ITERATION_ID:?Missing iteration ID}/timer/stop"

The request is idempotent. You can stop the timer after the run ends. This does
not reopen the run. Result submissions require an open run. An ended run rejects
them with 400.

8. Mark an iteration without rerunning it

Requires the TestRun:Update permission. Use
Mark an iteration status
to record a triage decision without running its steps again:

katalon_request --request POST \
  --header 'Content-Type: application/json' \
  --data '{"status":"FAILED","reason":"Checkout returned an error."}' \
  "${KATALON_API_HOST}/v2/manual-test/iterations/${ITERATION_ID:?Missing iteration ID}/mark"

The status must be PASSED, FAILED, BLOCKED, or SKIPPED; TODO is not
valid. A nonblank reason is appended to the actual-result text. The action
changes the current attempt in place and adds a MANUAL_OVERRIDE audit entry; it
does not create a re-execution. You can mark an iteration after the run ends, but
not after an abort.

9. Record a result and end a manual run

Requires the TestRun:Update permission. Use MANUAL_EXECUTION_ID from step 2
for these manual-run paths. Choose RESULT_ENVIRONMENT_ID from the run's
environment list.

Record a result for a non-data-bound test-case occurrence with
Update a manual test-case result.
The environmentId path parameter selects the environment; the optional
mtEnvironmentId body value does not replace it. Required body fields are the
testCaseId, testCaseOrder, and testCaseResult. If the run has suites,
include testSuiteId to identify the case occurrence:

For a new result with no timer, send END with a terminal result.

katalon_request --request POST \
  --header 'Content-Type: application/json' \
  --data '{
    "mtEnvironmentId": 402,
    "testSuiteId": 80,
    "testCaseId": 200,
    "testCaseOrder": 1,
    "testCaseResult": "PASSED",
    "timerStatus": "END",
    "executorType": "MANUAL"
  }' \
  "${KATALON_API_HOST}/v2/manual-test/executions/${MANUAL_EXECUTION_ID:?Missing manual execution ID}/environments/${RESULT_ENVIRONMENT_ID:?Missing environment ID}/results"

All IDs and order values are integers. testCaseResult accepts PASSED,
FAILED, BLOCKED, TODO, or SKIPPED. The API checks timerStatus against
the current timer state. TODO is in progress; the other values are terminal.

  • No timer or PAUSE: For TODO, send RUNNING. For a terminal result, send END.
  • RUNNING: For TODO, send RUNNING or PAUSE. For a terminal result, send END.
  • END: For TODO, send RUNNING. For a terminal-result correction, omit timerStatus.

You can provide startTime on its own. If you provide endTime, provide
startTime too. endTime must not precede startTime. Set duration only
with both timestamps. It uses seconds and must match their interval. The service
returns HTTP 201 with the result DTO when this request succeeds.

The API returns HTTP 400 with code 11008 when you send a result for a
data-bound case/environment. The service records data-bound results per
iteration. For an existing iteration, use Mark an iteration status
only to override its status without a rerun. The operation changes the current
attempt. It does not create a re-execution. Do not use this case-level operation
for a data-bound case.

End the manual run with an empty JSON object:

katalon_request --request POST \
  --header 'Content-Type: application/json' \
  --data '{}' \
  "${KATALON_API_HOST}/v2/manual-test/executions/${MANUAL_EXECUTION_ID:?Missing manual execution ID}/end"

The response is an object such as {"endTime":"2026-10-26T10:15:30.000+00:00"}.
You can provide an endTime. The API applies only results entries whose
testCaseResult is SKIPPED. Each such entry must include mtEnvironmentId;
the end path has no environment parameter. The service skips unfinished
iterations when it ends the run. The API submits the report in the background.
A successful response does not confirm report processing or TestOps run
completion.

Read the run's result page with
List results in a manual run:
Requires the TestRun:Read permission.

katalon_request --get "${KATALON_API_HOST}/v2/manual-test/executions/${MANUAL_EXECUTION_ID:?Missing manual execution ID}/results" \
  --data-urlencode 'pageToken=0' --data-urlencode 'size=10'

The response contains items, totalItems, size, and nextPageToken.
The API can return nextPageToken on the last page. Stop after you read
totalItems items or when items is empty. Do not continue only because a token
is present. The service uses page size 10 by default. It reduces values above 50
to 50. includeMetadata is false by default. Set it to true to include metadata.

Updated 17 days ago

Did this page help you?