> ## Documentation Index > Fetch the complete documentation index at: https://docs.usetuner.ai/llms.txt > Use this file to discover all available pages before exploring further. # Update Data Retention > Set a workspace's data-retention window and erasure scope. Both fields are optional and updated independently: a field you omit keeps its current value, while sending it as `null` clears it. Setting `retention_period_days` to `null` means "never delete" and always clears the erasure scope; any concrete window requires an `erasure_scope`. The window and the scope must both be included in the workspace's plan — the GET response lists what is available. If the plan can't be verified at all, the request fails with a 503 rather than a 402, **except** for clearing the policy (`retention_period_days: null`), which is always accepted: turning deletion off only ever stops erasure, so it must not depend on billing being reachable. Expired calls are erased by a nightly job, so a change takes effect on its next run rather than immediately. **Erasure is irreversible**: an erased call cannot be restored, and lowering the window makes more history eligible on the very next run. Simulation calls are never erased. ## OpenAPI ````yaml https://api.usetuner.ai/public/openapi.json put /api/v1/workspaces/{workspace_id}/data-retention openapi: 3.1.0 info: title: My Public API version: 1.0.0 servers: - url: https://api.usetuner.ai security: [] tags: - name: calls x-group: Calls - name: workspaces x-group: Workspaces - name: agent-settings x-group: Agent Settings - name: agents x-group: Agents - name: simulation x-group: Simulation - name: providers x-group: Providers paths: /api/v1/workspaces/{workspace_id}/data-retention: put: tags: - workspaces summary: Update Data Retention description: >- Set a workspace's data-retention window and erasure scope. Both fields are optional and updated independently: a field you omit keeps its current value, while sending it as `null` clears it. Setting `retention_period_days` to `null` means "never delete" and always clears the erasure scope; any concrete window requires an `erasure_scope`. The window and the scope must both be included in the workspace's plan — the GET response lists what is available. If the plan can't be verified at all, the request fails with a 503 rather than a 402, **except** for clearing the policy (`retention_period_days: null`), which is always accepted: turning deletion off only ever stops erasure, so it must not depend on billing being reachable. Expired calls are erased by a nightly job, so a change takes effect on its next run rather than immediately. **Erasure is irreversible**: an erased call cannot be restored, and lowering the window makes more history eligible on the very next run. Simulation calls are never erased. operationId: >- update_data_retention_settings_api_v1_workspaces__workspace_id__data_retention_put parameters: - name: workspace_id in: path required: true schema: type: integer description: Workspace ID. Find this in Workspace > General Settings. title: Workspace Id description: Workspace ID. Find this in Workspace > General Settings. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/DataRetentionUpdateRequest' responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/DataRetentionResponse' '401': description: Missing or invalid API key. content: application/json: example: detail: Not authenticated schema: $ref: '#/components/schemas/ErrorResponse' '402': description: >- The selected retention window or erasure scope isn't included in the workspace's plan. Check `allowed_retention_periods` and `allowed_erasure_scopes` on the GET response. content: application/json: example: detail: >- Selected retention period is not included in your current plan. schema: $ref: '#/components/schemas/ErrorResponse' '403': description: You do not have access to this workspace. content: application/json: example: detail: User does not have access to workspace 42 schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Workspace not found. content: application/json: example: detail: Workspace with ID 42 not found schema: $ref: '#/components/schemas/ErrorResponse' '422': description: >- A retention window was set without an erasure scope, or a field failed validation (`retention_period_days` must be a positive integer or null; `erasure_scope` must be one of the known scope tokens). content: application/json: example: detail: erasure_scope is required when a retention period is set. schema: $ref: '#/components/schemas/ErrorResponse' '503': description: >- The workspace's plan could not be verified, so the requested window and scope can't be checked against it. Retry shortly. Clearing the policy (`retention_period_days: null`) is accepted even then, since it only ever stops deletion. content: application/json: example: detail: >- Could not verify your plan's retention options right now. Please try again. schema: $ref: '#/components/schemas/ErrorResponse' security: - Bearer: [] components: schemas: DataRetentionUpdateRequest: properties: retention_period_days: anyOf: - type: integer - type: 'null' title: Retention Period Days description: >- Days a call is kept before it is erased. `null` means never delete and always clears `erasure_scope`. Omit the field to leave the current window unchanged. Must be one of the plan's `allowed_retention_periods`. examples: - 30 erasure_scope: anyOf: - type: string - type: 'null' enum: - transcript_recording - caller_data - full - null title: Erasure Scope description: >- What is destroyed when a call expires. `transcript_recording` removes the transcript, recording and log URLs; `caller_data` also removes the caller's identity and every free-text field derived from the conversation; `full` deletes the call record outright. Required whenever `retention_period_days` is set. Omit the field to leave the current scope unchanged. type: object title: DataRetentionUpdateRequest description: >- Request schema for updating a workspace's data-retention policy. Both fields are optional and support partial updates: a field omitted from the body is left unchanged, while a field sent as `null` clears that setting. DataRetentionResponse: properties: retention_period_days: anyOf: - type: integer - type: 'null' title: Retention Period Days description: Days a call is kept before it is erased. Null means never delete. erasure_scope: anyOf: - type: string - type: 'null' enum: - transcript_recording - caller_data - full - null title: Erasure Scope description: >- What is destroyed when a call expires. Null when nothing is ever deleted. allowed_retention_periods: items: anyOf: - type: integer - type: 'null' type: array title: Allowed Retention Periods description: >- Retention windows the workspace's plan allows, in days, ascending. Contains `null` when the plan permits never deleting. The update endpoint accepts only these values. allowed_erasure_scopes: items: enum: - transcript_recording - caller_data - full type: array title: Allowed Erasure Scopes description: >- Erasure scopes the workspace's plan allows, shallowest to deepest. The update endpoint accepts only these values. default_erasure_scope: anyOf: - type: string - type: 'null' enum: - transcript_recording - caller_data - full - null title: Default Erasure Scope description: >- The plan's default scope, useful to preselect when the workspace has none set yet. Null when the plan offers no scopes. type: object required: - retention_period_days - erasure_scope - allowed_retention_periods - allowed_erasure_scopes - default_erasure_scope title: DataRetentionResponse description: Response schema for the data-retention settings endpoints. ErrorResponse: properties: detail: type: string title: Detail description: Human-readable description of what went wrong. type: object required: - detail title: ErrorResponse description: Error body returned when a request fails. securitySchemes: Bearer: type: http description: >- Use Tuner API key (tr_api_...) or user session token. Find your API key in Workspace Settings > API Keys. scheme: bearer ````