Get started with reports and quality insights

Use report metadata to find a report, then request project-scoped quality insights
for an iteration. Report endpoints return metadata, not rendered dashboard or
chart rows; use the insight endpoints for computed results.

1. Set up authentication

Send requests to your tenant host, https://<tenant>.katalon.io, with no
trailing slash. Authenticate with a Katalon API key using HTTP Basic: leave the
username empty and use the key as the password. See
Authenticate with the v2 API.

Send x-project-id on every request. You can also send x-account-id (an
account UUID) and x-organization-id to select the account and organization
explicitly. Your key's user must have access to the project.

Set KATALON_API_HOST, KATALON_API_KEY, and KATALON_PROJECT_ID from your
environment. This Bash helper supplies the Basic credentials to curl through
standard input instead of placing the key in curl's command-line arguments. If
the key contains " or \, escape those characters as \" and \\ for
curl's configuration format. Do not enable shell tracing (set -x).

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}" \
    "$@"
}

Add optional account or organization headers to an individual curl request when
you need them; keep x-project-id on every call.

2. Find report metadata

List reports for the project. This endpoint returns metadata such as each
report's id, name, and slug; it does not return the report's chart rows.

katalon_request \
  "${KATALON_API_HOST}/v2/ra/web/metrics?page=0&size=20&sort=name,asc"

Pages start at 0. Read content and continue through the pages indicated by
totalPages and last. Only this list endpoint is paginated. Its sort query
uses property,direction syntax, for example name,asc; it does not use a
sorts parameter.

Choose an actual id from content and use it to read that report's metadata:
keep the ID and slug you select as REPORT_ID and REPORT_SLUG for the
examples below.

Use the numeric id, not embeddedDashboardId. The latter is an embed
identifier, not the report row ID accepted by the ID lookup.

katalon_request "${KATALON_API_HOST}/v2/ra/web/metrics/${REPORT_ID}"

You can also look up metadata by a returned slug:

katalon_request "${KATALON_API_HOST}/v2/ra/web/metrics/slug/${REPORT_SLUG}"

Use IDs and slugs from your own project response rather than copying example
identifiers.

3. Select an iteration

List iterations, optionally filtering by type and name, and save one
iteration's iterationName as ITERATION_NAME:

ITERATION_NAME=$(katalon_request \
  "${KATALON_API_HOST}/v2/ra/web/iterations?iterationType=RELEASE" |
  jq -er '.[0].iterationName')

The iteration response does not return an iterationType field. Keep the type
you requested (RELEASE in this example). Send both iterationType and
iterationName in each insight request below.

4. Request requirement insights for that iteration

The insight response contains computed coverage information. This example asks
for the selected iteration and the default detail level explicitly:

katalon_request --request POST \
  --header "Content-Type: application/json" \
  --data "{\"iterationType\":\"RELEASE\",\"iterationName\":\"${ITERATION_NAME}\",\"detailLevel\":\"ONLY_NON_QUALIFIED\"}" \
  "${KATALON_API_HOST}/v2/ra/web/insight/requirements"

coverageRate is a fraction, not
a 0–100 percentage, and can count fully and partially covered requirements.

Other project-scoped insight queries are available for defects, configurations,
test cases, common failures, and test flakiness. Their POST bodies are optional;
the request shape and response fields are in the reference pages:

5. Optionally request a bounded stability list

For an iteration-scoped stability query, supply the iteration type and name. Set
returnTests to the list you need and keep limitTests bounded; summary totals
describe the selected population, while each returned test list is limited.

katalon_request --request POST \
  --header "Content-Type: application/json" \
  --data "{\"filterType\":\"ITERATION\",\"iterationType\":\"RELEASE\",\"iterationName\":\"${ITERATION_NAME}\",\"returnTests\":[\"FLAKY\"],\"limitTests\":3}" \
  "${KATALON_API_HOST}/v2/ra/web/test-stability/test-cases/metrics"

An execution-scoped query instead uses filterType: "EXECUTION" and an
executionId.

1. Set up authentication

2. Find report metadata

3. Select an iteration

4. Request requirement insights for that iteration

5. Optionally request a bounded stability list

Reference pages