From 0284da29a24abe2ec576ca1e65bac2017a03c81f Mon Sep 17 00:00:00 2001 From: josebarrueta Date: Tue, 25 Aug 2026 11:07:19 -0700 Subject: [PATCH 1/3] docs(tool-executions): recording and retention are self-service The Retention section predates PLT-2978 and told readers to contact support for changes they can now make themselves. It was also wrong in three ways that matter more than the missing capability: - It offered project-level overrides. Project settings are an explicit non-goal; the value is organization-wide and nothing customer-reachable sets a project's own. - It folded turning recording off together with deleting history. They are different: recording off stops new runs being written and leaves stored ones to expire on the window. Shortening the window is the control that deletes, and it reaches records already held. - It gave no bounds, so a reader had no way to know 0 and 400 are refused. Rewritten around the two settings, what each does to history already held, and what a reader sees when the list is empty. --- .../governance/tool-executions/page.mdx | 49 +++++++++++++++++-- 1 file changed, 45 insertions(+), 4 deletions(-) diff --git a/app/en/operate/governance/tool-executions/page.mdx b/app/en/operate/governance/tool-executions/page.mdx index 451973f4a..f448326b7 100644 --- a/app/en/operate/governance/tool-executions/page.mdx +++ b/app/en/operate/governance/tool-executions/page.mdx @@ -3,9 +3,11 @@ title: "Tool Executions" description: "Review every tool run in a project: what ran, for whom, and why it failed, with tool inputs and outputs held to project admins." --- +import { Callout } from "nextra/components"; + # Tool executions -Arcade records every tool run in a project, including which tool ran, for which end user, when, and how it went, and exposes that history in the dashboard and over the API. +Arcade records every tool run in a project, including which tool ran, for which end user, when, and how it went, and exposes that history in the dashboard and over the API. Recording is on by default and is an organization-wide setting — see [Recording and retention](#recording-and-retention). This page serves two jobs: @@ -166,11 +168,50 @@ Two behaviors trip up API callers: Find your organization and project IDs in the dashboard URL: `/orgs/{org_id}/projects/{project_id}`. For the full request and response schemas, see the [API reference](/references/api). -## Retention +## Recording and retention + +Two settings govern the history, both organization-wide and both set by an organization admin. They apply to every project in the organization. + +| Setting | What it decides | +| -- | -- | +| Recording | Whether new tool runs are written down at all | +| Retention window | How long a recorded run is kept | + +Recording is on and the window is 7 days unless your organization changes them. Past the window, Arcade deletes the records and they stop appearing in the history and the API. + +### Change them yourself + +Open your organization in the dashboard and select **Execution Logging**, or call the API: + +```bash +curl -s -X PUT "https://api.arcade.dev/v1/orgs/{org_id}/logging-config" \ + -H "Authorization: Bearer $ARCADE_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{"logging_data_retention": "ALLOWED", "default_log_retention_days": 30}' +``` + +Send either field on its own; an omitted field is left alone, so changing the window cannot switch recording off by accident. + +A window must be at least 1 day and no longer than the platform maximum, which is 90 days on Arcade Cloud and is reported as `max_log_retention_days` on the organization read. Anything outside that is refused with a `422` rather than quietly adjusted. Zero is not "keep nothing" — it is refused, because turning recording off is the way to stop recording. + +Changing the policy takes organization-admin authority. The organization read reports `can_edit_logging` so a client can tell whether the caller may change it before offering the control. + +### What each setting does to history you already have + +These come apart, and the difference matters: + +- **Turning recording off** stops new runs being written down. It leaves what is already stored in place, and those records go on expiring under the window as before. It is not an erasure control. +- **Shortening the window** applies to records you already have. Going from 90 days to 7 deletes everything older than 7 days across every project in the organization, shortly after you save, and it cannot be undone. + +If you want existing history gone, shortening the window is the control that deletes it. + + +Turning recording on permits projects to record; it does not compel it. While recording is organization-wide the two are indistinguishable, and that stops being true if project-level settings arrive later. + -Execution logging runs by default, and each project keeps its history for a bounded retention window: 7 days unless your organization sets a different default or a project overrides it. Past the window, Arcade deletes the records and they stop appearing in the history and the API. +### When the history is empty -To change the retention window, or to turn off execution logging and delete the history for your organization, contact Arcade support. +An empty list has more than one cause, so the dashboard says which applies rather than leaving you to guess. If recording is off, Tool Executions says so instead of telling you that runs will appear once tools run. The project read also reports where the window in force came from and whether the project may change it, so a reader who cannot change it knows who to ask. ## Related content From 10d24ff323261056ff7d1aced42dd1480529d8ed Mon Sep 17 00:00:00 2001 From: josebarrueta Date: Tue, 25 Aug 2026 11:42:42 -0700 Subject: [PATCH 2/3] =?UTF-8?q?docs(tool-executions):=20Evan's=20review=20?= =?UTF-8?q?=E2=80=94=20tighter,=20and=20no=20unshipped=20behaviour?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Takes the suggested wording for the opening, the table, and the defaults sentence, and types the two settings. Drops four things: the org-admin authority line, which the opening now covers; two connective sentences that only restated the bullets under them; the callout about recording permitting rather than compelling, since project-level settings do not exist and the distinction has no observable effect until they do; and the empty-history section, which narrated UI copy the product already shows. The Callout import goes with its last use. --- .../governance/tool-executions/page.mdx | 24 ++++--------------- 1 file changed, 4 insertions(+), 20 deletions(-) diff --git a/app/en/operate/governance/tool-executions/page.mdx b/app/en/operate/governance/tool-executions/page.mdx index f448326b7..0bd4ca9d1 100644 --- a/app/en/operate/governance/tool-executions/page.mdx +++ b/app/en/operate/governance/tool-executions/page.mdx @@ -3,8 +3,6 @@ title: "Tool Executions" description: "Review every tool run in a project: what ran, for whom, and why it failed, with tool inputs and outputs held to project admins." --- -import { Callout } from "nextra/components"; - # Tool executions Arcade records every tool run in a project, including which tool ran, for which end user, when, and how it went, and exposes that history in the dashboard and over the API. Recording is on by default and is an organization-wide setting — see [Recording and retention](#recording-and-retention). @@ -170,14 +168,14 @@ Find your organization and project IDs in the dashboard URL: `/orgs/{org_id}/pro ## Recording and retention -Two settings govern the history, both organization-wide and both set by an organization admin. They apply to every project in the organization. +Two organization-wide settings govern the history, and are configured by an organization admin. They apply to every project in the organization. | Setting | What it decides | | -- | -- | -| Recording | Whether new tool runs are written down at all | -| Retention window | How long a recorded run is kept | +| Recording (boolean) | Whether new tool runs are written down at all | +| Retention window (number) | How long a recorded run is kept | -Recording is on and the window is 7 days unless your organization changes them. Past the window, Arcade deletes the records and they stop appearing in the history and the API. +By default, recording is enabled and the retention window is 7 days. Past the window, Arcade deletes the records and they stop appearing in the history and the API. ### Change them yourself @@ -194,25 +192,11 @@ Send either field on its own; an omitted field is left alone, so changing the wi A window must be at least 1 day and no longer than the platform maximum, which is 90 days on Arcade Cloud and is reported as `max_log_retention_days` on the organization read. Anything outside that is refused with a `422` rather than quietly adjusted. Zero is not "keep nothing" — it is refused, because turning recording off is the way to stop recording. -Changing the policy takes organization-admin authority. The organization read reports `can_edit_logging` so a client can tell whether the caller may change it before offering the control. - ### What each setting does to history you already have -These come apart, and the difference matters: - - **Turning recording off** stops new runs being written down. It leaves what is already stored in place, and those records go on expiring under the window as before. It is not an erasure control. - **Shortening the window** applies to records you already have. Going from 90 days to 7 deletes everything older than 7 days across every project in the organization, shortly after you save, and it cannot be undone. -If you want existing history gone, shortening the window is the control that deletes it. - - -Turning recording on permits projects to record; it does not compel it. While recording is organization-wide the two are indistinguishable, and that stops being true if project-level settings arrive later. - - -### When the history is empty - -An empty list has more than one cause, so the dashboard says which applies rather than leaving you to guess. If recording is off, Tool Executions says so instead of telling you that runs will appear once tools run. The project read also reports where the window in force came from and whether the project may change it, so a reader who cannot change it knows who to ask. - ## Related content - [Audit Logs](/operate/governance/audit-logs): administrative actions across the platform From df4f7551ed8c8e04e79b7e06d1d9d12cf61e5692 Mon Sep 17 00:00:00 2001 From: josebarrueta Date: Tue, 25 Aug 2026 11:49:21 -0700 Subject: [PATCH 3/3] docs(tool-executions): scope the defaults to Arcade Cloud "By default, recording is enabled" holds for Arcade Cloud, where the organization starts at ALLOWED and projects start enabled. It does not hold for a self-hosted deployment: the Engine's execution_logging.enabled defaults to false, and with it off no run is recorded and no retention worker runs, whatever the organization's policy says. The paragraph two below already scopes the maximum to Arcade Cloud, so this now reads consistently, with one clause for the self-hosted case. --- app/en/operate/governance/tool-executions/page.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/app/en/operate/governance/tool-executions/page.mdx b/app/en/operate/governance/tool-executions/page.mdx index 0bd4ca9d1..025b167df 100644 --- a/app/en/operate/governance/tool-executions/page.mdx +++ b/app/en/operate/governance/tool-executions/page.mdx @@ -175,7 +175,7 @@ Two organization-wide settings govern the history, and are configured by an orga | Recording (boolean) | Whether new tool runs are written down at all | | Retention window (number) | How long a recorded run is kept | -By default, recording is enabled and the retention window is 7 days. Past the window, Arcade deletes the records and they stop appearing in the history and the API. +On Arcade Cloud, recording is enabled by default and the retention window is 7 days. Past the window, Arcade deletes the records and they stop appearing in the history and the API. A self-hosted deployment sets its own defaults, and records nothing until execution logging is turned on in the Engine configuration. ### Change them yourself