> For the complete documentation index, see [llms.txt](https://learning.contextqa.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://learning.contextqa.com/enterprise-application-testing/api-testing/load-testing.md).

# API Load Testing

Build ContextQA API load tests with virtual-user stages, latency and error thresholds, live metrics, k6 export, and baseline-versus-candidate comparisons.

> **Documentation owner:** [Deep Barot](https://contextqa.com/academy/) · **Last updated:** November 11, 2026

## Quick answer

Create a load test from an ordered set of API test cases, select the environment, define virtual-user stages, and set pass/fail thresholds. Run the saved configuration, inspect live and final metrics, then compare two equivalent runs. A completed run with no requests or no threshold evidence does not establish acceptable performance.

## Key takeaways

* Reuse API journeys and keep their order and test data explicit.
* Define load stages and thresholds before evaluating a candidate.
* Compare equivalent environments and distinguish completion from a passing verdict.

## What can ContextQA load testing measure?

The load-testing workflow turns API cases into a k6-based workload. It reports request volume, request rate, error rate, latency percentiles, endpoint statistics, runner state, and threshold outcomes. Use it to assess how an API behaves under a defined workload, alongside functional regression tests.

## Before you start

Use an environment approved for the planned load, working API cases, and data suitable for concurrent requests. Decide the representative journey, expected traffic shape, maximum virtual users, and stopping conditions. Avoid shared mutable records that make concurrent users invalidate one another's setup.

## Build the workload

1. Open **Load Testing** and create a new load test.
2. Enter its name and purpose.
3. Select the **API test cases** each virtual user should run, and put them in the intended order.
4. Select the target environment.
5. Set **Think time between iterations (ms)** and **Graceful stop (s)**.
6. Add load-profile stages. Each stage specifies **Duration (s)** and **Target VUs**.
7. Add pass/fail thresholds, then save the definition.
8. Review **Preview k6 script** or **Export k6** when you need to inspect the generated workload.

Unsaved changes must be saved before running or exporting the definition. The number of runners is a per-run choice and is separate from the workload's virtual-user targets.

## Choose useful thresholds

| Metric           | Available statistic                  | Question it answers                        |
| ---------------- | ------------------------------------ | ------------------------------------------ |
| Request duration | p50, p90, p95, p99, average, maximum | How long do requests take under this load? |
| Failed requests  | Rate                                 | What share of requests fail?               |
| Request count    | Rate                                 | What throughput does the workload achieve? |

Use the operators and units shown by the editor. Set thresholds from the service's requirements and baseline instead of copying a universal target. A latency percentile without request volume and error rate can hide a failing workload.

## Run and inspect

Start **Run load test**. Follow queued, dispatching, running, and aggregating states to the terminal result. Review runner status, warnings, request count, latency, error rate, and per-endpoint results. A cancelled run or a metric with no data is not a passing threshold.

If a run sends zero requests, inspect selected cases, stages, startup errors, and target access. Do not interpret empty charts as zero latency or zero defects.

## Compare a baseline and candidate

Select exactly two runs and choose **Compare selected**. Keep the environment, workload definition, test data, load stages, and relevant infrastructure comparable. Record both build identifiers. Investigate differences in latency, errors, throughput, and individual endpoints together.

## Frequently asked questions

### Does a functional test pass prove capacity?

No. A single functional execution verifies behavior under its own conditions. Load testing adds a defined concurrency and traffic pattern; the result applies to that workload and environment.

### Can I export the workload?

Use **Export k6** after saving. Review the exported script and its credential handling before sharing it or running it outside ContextQA.

### How does load testing affect release readiness?

Add the workload definition, baseline/candidate results, threshold outcomes, and unresolved bottlenecks to the [release record](https://learning.contextqa.com/enterprise-application-testing/ship/release-readiness.md). Pair performance evidence with functional and integration coverage.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://learning.contextqa.com/enterprise-application-testing/api-testing/load-testing.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
