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 the
authentication reference.

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:

katalon_request \
  "${KATALON_API_HOST}/v2/ra/web/iterations?iterationType=RELEASE"

Use an iteration's returned iterationName and the type you requested (RELEASE
in this example) in an insight request. The iteration response does not return
an iterationType field. The request body is optional at
the API boundary, but include both selectors in this example instead of relying
on an omitted selector or an assumed default.

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"

Replace <ITERATION_NAME> with the exact name returned for your project. The
body fields are optional in the API contract; supplying both iteration
selectors makes the intended scope explicit. 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"

Replace the placeholder with the iteration name returned for your project. An
execution-scoped query instead uses filterType: "EXECUTION" and an
executionId. Do not assume a date-string timezone or wire-format guarantee
for date-based selectors; this guide uses iteration selectors instead.

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