---
title: "set_log_retention"
description: "Generated reference for the management action set_log_retention: its description, access metadata, payload contract, and registration status."
slug: /reference/actions/set-log-retention
order: 17
visibility: public
redirects_from: []
---

# set\_log\_retention

Generated automatically from the [published contract sources](/cloud/reference/about/#contract-sources).

A script calls this action over HTTPS at `POST https://tzcloud.turnzero.ai/v1/set_log_retention`, with a bearer credential and the action's payload as the JSON body. An MCP connection lists this action as the tool `tzcloud_set_log_retention`.

OAuth access tokens and minted tokens, including the turnzero command's computer token, are bearer credentials. The action determines which kinds, scopes and grants it accepts ([Sign-in, sessions, and tokens](/cloud/concepts/sign-in-sessions-and-tokens/)).

**Build metadata:** Registered in this build. Registration describes the default dispatcher in this build. It does not guarantee that a caller has the required credential or grant, that a tool is listed for that connection, or that the required service is configured.

## Contract description

Turn your application's longer log retention on or off\. The account owner must have requested or agreed to turning this option on or off\. If their choice is missing and nobody can answer, leave it unchanged and report\. Turning it on charges for the days left in the calendar month, including today\. A repeat charges nothing\. Turning it off gives nothing back\. The next retention run deletes entries older than seven days\. Turning it on again cannot restore them\. The answer's `log_retention_days` is the recorded state\. Nothing continues in the background for this act\.

## More about this action

Pass `days` as 30 to turn the option on or 7 to turn it off\. Turning it on sets the option only after the month's charge is posted or already covered\. An unbilled account bypasses the balance check and incurs no real charge\. The option has its own retained\-bytes bound; log writes past it refuse `log_capacity_reached`\.

Every call before pricing reads usage refuses `invalid_request`, as do other days values and an application on the unlimited plan\. `no_such_application` means the id is absent from your account\. A turn\-on refuses `balance_short` where balance left is not more than the month's charge for the days left\. `rates_unread` means rate rows or the switch instant could not be read when a new charge was needed; nothing was charged, so try shortly\. `option_not_set` means the option was not turned on, and any posted charge remains\. If the application still exists, retry: in the same UTC calendar month, no further charge is posted while the month's charged count covers your log options, including this one\. Turning off charges nothing\. No further state read is needed beyond the returned `log_retention_days`\.

## Access and action metadata

```json
{
  "name": "set_log_retention",
  "resource": "application",
  "tier": "reversible",
  "surface": "tzcloud",
  "addresses": [
    "tzcloud"
  ],
  "product": "cloud",
  "summary": "Turn your application's longer log retention on or off. Turn this option on or off only at the account owner's request. If their choice is missing and nobody can answer, leave it unchanged and report. Turning it on charges for the days left in the calendar month, including today. A repeat charges nothing. Turning it off gives nothing back. The next retention run deletes entries older than seven days. Turning it on again cannot restore them. The answer's `log_retention_days` is the recorded state. Nothing continues in the background for this act.\n\nPass `days` as 30 to turn the option on or 7 to turn it off. Turning it on sets the option only after the month's charge is posted or already covered. An unbilled account bypasses the balance check and incurs no real charge. The option has its own retained-bytes bound; log writes past it refuse `log_capacity_reached`.\n\nEvery call before pricing reads usage refuses `invalid_request`, as do other days values and an application that holds no size. `no_such_application` means the id is absent from your account. A turn-on refuses `balance_short` where balance left is not more than the month's charge for the days left. `rates_unread` means rate rows or the switch instant could not be read when a new charge was needed; nothing was charged, so try shortly. `option_not_set` means the option was not turned on, and any posted charge remains. If the application still exists, retry: in the same UTC calendar month, no further charge is posted while the month's charged count covers your log options, including this one. Turning off charges nothing. No further state read is needed beyond the returned `log_retention_days`.",
  "annotations": {
    "readOnlyHint": false,
    "destructiveHint": true,
    "openWorldHint": false,
    "idempotentHint": true
  }
}
```

## MCP catalog entry

```json
{
  "name": "set_log_retention",
  "title": "Set log retention",
  "tier": "reversible",
  "scenario": "CHI-L0-09",
  "summary": "Turn your application's longer log retention on or off. The account owner must have requested or agreed to turning this option on or off. If their choice is missing and nobody can answer, leave it unchanged and report. Turning it on charges for the days left in the calendar month, including today. A repeat charges nothing. Turning it off gives nothing back. The next retention run deletes entries older than seven days. Turning it on again cannot restore them. The answer's `log_retention_days` is the recorded state. Nothing continues in the background for this act.",
  "owners": [
    "API-L0-29",
    "ACB-L0-26",
    "LGS-L0-14",
    "PRC-L0-16"
  ]
}
```

## request

| JSON pointer | Description and constraints |
|---|---|
| "" \(root\) | Type: object<br>Required fields: \["application","days"\] |
| /<wbr>properties/<wbr>application | Your account's application `id` from `list_applications`, not its name or label\.<br><br>Type: string |
| /<wbr>properties/<wbr>days | 30 turns longer log retention on; 7 turns it off\. Turning off lets the next retention run delete older entries permanently\.<br><br>Type: integer<br>Allowed values: \[7,30\] |

## response

| JSON pointer | Description and constraints |
|---|---|
| "" \(root\) | Type: object<br>Required fields: \["contract\_version","application","log\_retention\_days","changed"\] |
| /<wbr>properties/<wbr>contract\_version | Required value: 1 |
| /<wbr>properties/<wbr>reference | The short reference the platform recorded your call under: ten lowercase hexadecimal characters, the value in the call’s record row\. Quote it when you report the call\.<br><br>Type: string<br>Pattern: ^\[0\-9a\-f\]\{10\}$ |
| /<wbr>properties/<wbr>application | The application id\.<br><br>Type: string |
| /<wbr>properties/<wbr>log\_retention\_days | The retention days now held by the application\.<br><br>Type: integer<br>Allowed values: \[7,30\] |
| /<wbr>properties/<wbr>changed | False when the requested retention was already held and no charge was posted\.<br><br>Type: boolean |

## Complete payload contract

```json
{
  "request": {
    "type": "object",
    "required": [
      "application",
      "days"
    ],
    "properties": {
      "application": {
        "type": "string",
        "description": "Your account's application `id` from `list_applications`, not its name or label."
      },
      "days": {
        "type": "integer",
        "enum": [
          7,
          30
        ],
        "description": "30 turns longer log retention on; 7 turns it off. Turning off lets the next retention run delete older entries permanently."
      }
    }
  },
  "response": {
    "type": "object",
    "required": [
      "contract_version",
      "application",
      "log_retention_days",
      "changed"
    ],
    "properties": {
      "contract_version": {
        "const": 1
      },
      "reference": {
        "type": "string",
        "pattern": "^[0-9a-f]{10}$",
        "description": "The short reference the platform recorded your call under: ten lowercase hexadecimal characters, the value in the call’s record row. Quote it when you report the call."
      },
      "application": {
        "type": "string",
        "description": "The application id."
      },
      "log_retention_days": {
        "type": "integer",
        "enum": [
          7,
          30
        ],
        "description": "The retention days now held by the application."
      },
      "changed": {
        "type": "boolean",
        "description": "False when the requested retention was already held and no charge was posted."
      }
    }
  }
}
```

## Shared contracts

- [Refusals](/cloud/reference/refusals/): every refusal, by surface, with its cause and its remedy
- [schemas/wire\_error\.schema\.json](/cloud/reference/sources/schemas/wire-error-schema/)
- [schemas/wire\_errors\.json](/cloud/reference/sources/schemas/wire-errors/)
- [schemas/action\_payloads\.json](/cloud/reference/sources/schemas/action-payloads/) (includes shared shapes)
- [management\_api\_contract\.md](/cloud/reference/sources/management-api-contract/)
