Configuration: API Testing: Retention
Overview
Use this page to configure API testing data retention windows. API Testing Retention controls how long completed flow runs, captured request/response artifacts, API definition versions, and debug events stay in the platform before a background cleanup process permanently deletes them. Without these limits, data from every API testing run would accumulate indefinitely and consume storage; set too aggressively, you lose the history needed to debug a failed run or compare an API's past definitions.
These windows apply to data generated by flows you build in API Testing: Flows, whether run directly, on a schedule through API Testing: Schedules, or reviewed afterward in API Testing: Run History. The API definition versions this page ages out originate from the sources you manage in API Testing: API Sources. You don't need to create anything before opening this page, but the settings only matter once flows are producing runs, artifacts, and versions for the cleanup process to act on.
On this page, you can review and adjust four numeric windows: how often the cleanup process runs, how long completed runs are kept, how long captured artifacts are kept, and how long API definition versions are kept. You can also click Refresh to confirm you're viewing the current saved values.
Key concepts
- Flow run - A single execution of an API testing flow, including its node-level results and event logs. (related: API Testing: Flows)
- Artifact - The captured HTTP request and response bodies recorded during a flow run, used to inspect the exact payloads sent and received. (related: API Testing: Run History)
- API definition version - A saved snapshot of an API source's definition together with the diff against the previous snapshot. (related: API Testing: API Sources)
- Background cleanup process - A scheduled job that permanently deletes flow runs, artifacts, versions, and debug events once they are older than their configured retention window.
When to use it
- You need to reduce storage consumption by shortening how long completed flow runs or captured artifacts are kept.
- You need to keep flow run history longer for compliance review or a long-running investigation.
- You want the background cleanup process to run more or less frequently.
- You're troubleshooting why older flow runs, artifacts, or API definition versions no longer appear in API Testing: Run History.
- You need to extend how long API definition version history and diffs are retained before an audit.
Before you begin
- You have permission to edit platform-wide configuration settings, managed under Operations: Permissions.
- You have at least one flow configured in API Testing: Flows, since retention settings only affect data once flows have produced runs, artifacts, or versions.
- If you plan to shorten a window, confirm with your team that the older runs, artifacts, or versions it will remove are no longer needed, since the background cleanup process deletes them permanently.
Common workflows
Shorten a retention window to save storage
Persona: Platform administrator managing storage usage
- Open API Testing Retention from Configuration.
- Expect: The Retention Windows panel loads showing the current Cleanup Interval (hours), Run Retention (days), Artifact Retention (days), and Version Retention (months) values.
- Replace the value in Artifact Retention (days) with a lower number, for example 7.
- Expect: The field displays the new number you entered.
- Click Refresh to reload the page's values from the server.
- Expect: The panel re-displays the four retention fields with whatever value is currently stored on the server.
Verify: Artifact Retention (days) shows the lower number after Refresh, confirming the change was saved. If it reverts to the old value, the edit did not persist; re-enter it and check for a save confirmation before leaving the page.
Steps
Step 1
Open the API Testing Retention page.
Expected result: The Retention Windows panel loads with four fields populated: Cleanup Interval (hours) at 6, Run Retention (days) at 180, Artifact Retention (days) at 30, and Version Retention (months) at 12.
Reviewing the current windows is the starting point before you decide whether any of them need to change.
- A separate Credentials expiring banner may appear over the content area; it is unrelated to retention settings.
-
Refresh sits in the top-right of the Retention Windows panel.
Step 2
Click Refresh.
Expected result: The panel reloads the four retention values from the server; in this case all four fields keep their prior values. The Credentials expiring banner that was visible on the previous screen is no longer shown, which is unrelated to the retention fields themselves.
Refreshing confirms you're looking at the currently saved retention windows rather than a stale or locally edited view.
-
Cleanup Interval (hours), Run Retention (days), Artifact Retention (days), and Version Retention (months) remain at their previous values after the refresh.
Field reference
| Field | Purpose | Format / Validation | Required | Default |
|---|---|---|---|---|
| Cleanup Interval (hours) | Controls how often the background cleanup process checks for and removes data past its retention window. Lower it to remove aged-out data sooner after it expires; raise it to run the cleanup job less often, which reduces database load at the cost of expired data lingering longer between runs. | Whole number, hours | No | 6 |
| Run Retention (days) | Controls how many days a completed flow run, plus its cascaded node runs and event logs, is kept before cleanup deletes it. Lower it to reduce storage used by run history; raise it to keep a longer run history available in API Testing: Run History for troubleshooting or trend analysis. | Whole number, days | No | 180 |
| Artifact Retention (days) | Controls how many days captured HTTP request and response bodies are kept. Lower it to reduce storage used by large captured payloads; raise it to keep exact request/response data available longer for debugging failed or unexpected flow results. | Whole number, days | No | 30 |
| Version Retention (months) | Controls how many months API definition versions and their diffs are kept. Lower it to limit how far back you can compare API definition changes; raise it to preserve a longer change history for audits or regression investigation. | Whole number, months | No | 12 |
Controls reference
Refresh
Reloads the four retention fields from the server.
When to use: Use it to confirm you're viewing the current saved values, for example after editing a field or if you suspect someone else changed the settings.
Side effects: Read-only: it re-fetches and redisplays the current values without changing any stored retention setting.
Close (credentials banner)
Dismisses the Credentials expiring notification banner that can appear over this panel.
When to use: Use it to clear the banner from view once you've noted or acted on the warning; it is unrelated to the retention settings below it.
Side effects: Read-only with respect to retention settings: it only hides the notification banner, it does not change any retention value or the underlying credential.
Verify the result
After you change one or more retention fields and click Refresh, each field shows the number you entered rather than reverting to its previous value, confirming the new window was saved. Data older than a shortened window (flow runs, artifacts, versions, or debug events) stops appearing in API Testing: Run History only after the next Cleanup Interval (hours) cycle runs, not immediately. If a field reverts to its old value after Refresh, the change was not saved and you need to re-enter it. If old data still appears in Run History right after shortening a window, wait for the next cleanup cycle before assuming the setting didn't take effect.
Troubleshooting
- Symptom: You change a retention value but can't find a way to confirm it saved. Fix: Click Refresh and check whether the field still shows your new number; if it reverts to the old value, re-enter it and look for a save confirmation before leaving the page.
- Symptom: Old flow runs or artifacts still appear in API Testing: Run History after lowering Run Retention (days) or Artifact Retention (days). Fix: Wait for the next Cleanup Interval (hours) cycle, since the cleanup process only deletes data at that interval, not instantly when you change the setting.
- Symptom: The Credentials expiring banner covers part of the Retention Windows panel. Fix: Dismiss it with its close control, or reissue the expiring credential under Configuration: Credential Profiles; it is unrelated to retention settings.
- Symptom: You need API definition version history for an audit but Version Retention (months) is set low. Fix: Increase Version Retention (months) before the audit window elapses, since versions and diffs older than the configured number of months are deleted by cleanup.
- Symptom: Cleanup runs more often than you'd like. Fix: Raise Cleanup Interval (hours); this field only controls how often the cleanup process runs, not how much data it removes each time.
Related articles
- Prerequisite: API Testing: Flows - flow runs retained by this page are produced by flows defined there
- Next step: API Testing: Run History - retained flow runs and artifacts are viewed there until they age out
- See also: API Testing: API Sources - the API definition versions this page ages out originate from sources managed there
- See also: Configuration: Credential Profiles - the expiring credential shown in this page's banner is reissued there
- See also: API Testing: Schedules - scheduled flow runs generate the data this page's retention windows apply to