Configuration: API Testing: Retention
Overview
Use this page to review and adjust API testing data retention windows. API Testing accumulates flow runs, the HTTP request and response bodies it captures as artifacts, and the versions it keeps of API definitions and their diffs every time a flow executes. Without limits, this history grows indefinitely and consumes storage, so this page sets the numeric windows a background cleanup process uses to decide when flow runs, artifacts, and versions are old enough to delete.
These windows apply to data produced elsewhere in API Testing: flows you build and run from API Testing: Flows, executions triggered by API Testing: Schedules, and the results you review in API Testing: Run History. The retention settings here do not create or run anything themselves, they only determine how long that output remains visible and queryable before the background cleanup process removes it permanently.
On this page you can see the current Cleanup Interval, Run Retention, Artifact Retention, and Version Retention values, change any of them to match how long you need to keep test history for debugging or audits, and use Refresh to confirm the stored configuration reflects your changes.
Key concepts
- flow run - A single recorded execution of an API Testing flow, including its cascaded node runs and event logs. (related: API Testing: Run History)
- artifact - The captured HTTP request and response bodies recorded during a flow run, kept separately from the run's status and timing. (related: API Testing: Flows)
- API definition version - A saved snapshot of a flow or API definition together with the diff from the version before it. (related: API Testing: Flows)
- background cleanup - The scheduled process that deletes flow runs, artifacts, and versions once they are older than the retention window configured for them.
When to use it
- When API Testing storage usage is growing and you want to shorten how long runs, artifacts, or versions are kept.
- When you need to retain run history or captured request/response bodies longer for an audit or an incident investigation, before the cleanup deletes them.
- When you're troubleshooting why older flow runs, artifacts, or API definition versions are no longer visible in API Testing: Run History or API Testing: Flows.
- When you're tuning how frequently the background cleanup runs to balance storage reclaim speed against system load.
- When setting up a new API Testing environment and you want retention policy in place before test traffic accumulates history.
Before you begin
- Review your current API Testing volume in API Testing: Flows and API Testing: Run History so you can judge whether a longer or shorter window is appropriate before changing it.
- Confirm how long you need to keep run history, captured bodies, or definition versions for audits or debugging before shortening a window; the background cleanup deletes data once it ages out and the deletion cannot be undone.
Common workflows
Shorten a retention window to reduce storage use
Persona: Load-test admin managing API Testing storage
- Note the current value in Artifact Retention (days).
- Expect: The field shows the stored number of days, for example 30.
- Replace the value with a smaller number of days that still covers your debugging window.
- Expect: The field shows the number you typed.
- Select Refresh to check whether the new value was recorded.
- Expect: The panel reloads the stored values; if Artifact Retention (days) still shows your new number, the change was saved, if it reverts to the previous number, it was not.
Verify: Artifact Retention (days) shows your reduced number after a refresh, and captured request/response bodies older than that window are removed the next time the background cleanup runs.
Extend run retention for an audit
Persona: Load-test admin preparing for an audit or investigation
- Note the current value in Run Retention (days).
- Expect: The field shows the stored number of days, for example 180.
- Increase the value to cover the period you need to keep for the audit.
- Expect: The field shows the larger number you typed.
- Select Refresh to confirm the new value persisted.
- Expect: The panel reloads the stored values; the field continues to show your increased number if the change was saved.
Verify: Run Retention (days) displays the increased number, and flow runs within that longer window remain visible in API Testing: Run History instead of being removed by the background cleanup.
Steps
Step 1
Open Retention from the Configuration section.
Expected result: The API Testing Retention panel loads with the Retention Windows group showing four current values: Cleanup Interval (hours) at 6, Run Retention (days) at 180, Artifact Retention (days) at 30, and Version Retention (months) at 12.
This is the starting point for reviewing or changing how long API Testing data is kept before the background cleanup deletes it.
- Cleanup Interval (hours), Run Retention (days), Artifact Retention (days), and Version Retention (months) each display the value currently stored on the server.
-
Refresh sits at the top right of the Retention Windows panel.
Field reference
| Field | Purpose | Format / Validation | Required | Default |
|---|---|---|---|---|
| Cleanup Interval (hours) | Sets how often the background cleanup process runs. A lower number reclaims storage sooner by running cleanup more frequently in smaller batches; a higher number batches deletion into fewer, larger runs and delays how quickly storage is freed after you shorten one of the other windows. | integer, hours | No | 6 |
| Run Retention (days) | Controls how long completed flow runs, along with their cascaded node runs and event logs, stay available before cleanup deletes them. Raise it to keep a longer run history for investigations; lower it to reduce the storage used by historical run data. | integer, days | No | 180 |
| Artifact Retention (days) | Controls how long captured HTTP request/response bodies are kept. Artifacts can be large, so raising this value preserves request/response evidence longer for debugging failed flows at the cost of more storage, while lowering it frees storage sooner without affecting how long the run record itself (set by Run Retention) survives. | integer, days | No | 30 |
| Version Retention (months) | Controls how long API definition versions and their diffs are kept. Raise it to retain a longer change history to compare definitions against; lower it to prune older versions you no longer need. | integer, months | No | 12 |
Controls reference
Refresh
Reloads the Cleanup Interval, Run Retention, Artifact Retention, and Version Retention fields from the currently stored configuration.
When to use: Use it after changing a value to confirm whether the change was recorded, or to discard an edit you have not committed by restoring the last saved numbers.
Side effects: Read-only: it does not change the stored retention configuration, it only re-reads it into the panel, replacing any unsaved edit in a field with the stored value.
Verify the result
After adjusting a retention window, the field displays the new number you entered. Select Refresh to reload the panel from the stored configuration: if the field still shows your new value, the change was recorded, if it reverts to the previous number, it was not saved and you need to re-enter it. The effect on stored data is not immediate: the background cleanup only deletes runs, artifacts, or versions older than the configured window the next time it runs, at the cadence set by Cleanup Interval (hours). If data you expected to be gone is still present in API Testing: Run History or API Testing: Flows, the cleanup interval likely has not elapsed yet rather than the retention value being wrong.
Troubleshooting
- Symptom: You change a value and Refresh shows the old number again. Fix: The edit was not saved; re-enter the value and confirm it before navigating away or refreshing, since this panel only keeps a change once it has been committed.
- Symptom: Flow runs or artifacts disappear sooner than expected from API Testing: Run History. Fix: Check Run Retention (days) and Artifact Retention (days) here; the background cleanup deletes data once it is older than the configured window, and the deletion cannot be reversed.
- Symptom: Storage used by API Testing keeps growing even after you lower a retention value. Fix: A lowered window only takes effect at the next run of the background cleanup, set by Cleanup Interval (hours); wait for the next interval or temporarily reduce the interval to reclaim storage sooner.
- Symptom: Older API definition versions you expected to compare against are missing. Fix: Check Version Retention (months); versions and diffs older than this window are pruned by the background cleanup and cannot be recovered.
- Symptom: Edits to a retention field don't stick after you navigate away. Fix: Confirm your account has Configuration edit rights for API Testing retention; accounts without edit rights can view the stored windows here but cannot change them.
Related articles
- See also: API Testing: Flows - flows generate the runs and definition versions whose retention this page controls
- See also: API Testing: Run History - view the flow runs currently kept within the Run Retention window
- See also: API Testing: Schedules - scheduled flow runs are a main source of the run and artifact volume this page manages