<!-- llms.txt: https://workos.com/llms.txt -->

# Audit Log Retention

Retention settings control how long Audit Log events are stored before being permanently deleted. You can configure the retention period on a per-organization basis.

## Get Retention

Get the configured event retention period for the given Organization.

:::code-group

```bash language="curl" title="Request" tab="1"
curl "https://api.workos.com/organizations/org_01EHZNVPK3SFK441A1RGBFSHRT/audit_logs_retention" \
  --header "Authorization: Bearer sk_example_123456789"
```

```rb language="ruby" title="Request" tab="1"
require "workos"

WorkOS.configure do |config|
  config.api_key = "sk_example_123456789"
end

WorkOS.client.audit_logs.get_organization_audit_logs_retention(id: "org_01EHZNVPK3SFK441A1RGBFSHRT")
```

```py language="python" title="Request" tab="1"
from workos import WorkOSClient

client = WorkOSClient(api_key="sk_example_123456789", client_id="client_123456789")

client.audit_logs.get_organization_audit_logs_retention(
    id_="org_01EHZNVPK3SFK441A1RGBFSHRT"
)
```

```go language="go" title="Request" tab="1"
package main

import (
	"context"

	"github.com/workos/workos-go/v10"
)

func main() {
	client := workos.NewClient("sk_example_123456789")

	_, err := client.AuditLogs().GetOrganizationAuditLogsRetention(context.Background(), "org_01EHZNVPK3SFK441A1RGBFSHRT")
	if err != nil {
		panic(err)
	}
}
```

```php language="php" title="Request" tab="1"
<?php

use WorkOS\WorkOS;

$workos = new WorkOS(
    apiKey: "sk_example_123456789",
    clientId: "client_123456789",
);

$workos
    ->auditLogs()
    ->getOrganizationAuditLogsRetention(id: "org_01EHZNVPK3SFK441A1RGBFSHRT");
```

```java language="java" title="Request" tab="1"
import com.workos.WorkOS;

WorkOS workos = new WorkOS("sk_example_123456789");

workos.auditLogs.getOrganizationAuditLogsRetention("org_01EHZNVPK3SFK441A1RGBFSHRT");
```

```cs language="dotnet" title="Request" tab="1"
using WorkOS;

var client = new WorkOSClient(new WorkOSOptions {
    ApiKey = "sk_example_123456789",
    ClientId = "client_123456789",
});

await client.AuditLogs.GetOrganizationAuditLogsRetentionAsync("org_01EHZNVPK3SFK441A1RGBFSHRT");
```

```rust language="rust" title="Request" tab="1"
use workos::Client;

#[tokio::main]
async fn main() -> Result<(), workos::Error> {
    let client = Client::builder()
        .api_key("sk_example_123456789")
        .client_id("client_123456789")
        .build();

    let _result = client
        .audit_logs()
        .get_organization_audit_logs_retention("org_01EHZNVPK3SFK441A1RGBFSHRT")
        .await?;

    Ok(())
}
```

```json language="json" title="Response" tab="2"
{
  "retention_period_in_days": 30
}
```

:::

## Set Retention

Set the event retention period for the given Organization.

:::code-group

```bash language="curl" title="Request" tab="1"
curl --request PUT \
  --url "https://api.workos.com/organizations/org_01EHZNVPK3SFK441A1RGBFSHRT/audit_logs_retention" \
  --header "Authorization: Bearer sk_example_123456789" \
  --header "Content-Type: application/json" \
  -d @- <<'BODY'
    {
        "retention_period": "1_MONTH"
    }
BODY
```

```rb language="ruby" title="Request" tab="1"
# workos:manual - preserve the retention enum argument
require "workos"

WorkOS.configure do |config|
  config.api_key = "sk_example_123456789"
end

WorkOS.client.audit_logs.update_organization_audit_logs_retention(
  id: "org_01EHZNVPK3SFK441A1RGBFSHRT",
  retention_period: "1_MONTH"
)
```

```py language="python" title="Request" tab="1"
# workos:manual - preserve the retention enum argument
from workos import WorkOSClient

client = WorkOSClient(api_key="sk_example_123456789", client_id="client_123456789")

client.audit_logs.update_organization_audit_logs_retention(
    id_="org_01EHZNVPK3SFK441A1RGBFSHRT", retention_period="1_MONTH"
)
```

```go language="go" title="Request" tab="1"
// workos:manual - preserve the retention enum argument
package main

import (
	"context"

	"github.com/workos/workos-go/v10"
)

func main() {
	client := workos.NewClient("sk_example_123456789")

	_, err := client.AuditLogs().UpdateOrganizationAuditLogsRetention(context.Background(), "org_01EHZNVPK3SFK441A1RGBFSHRT", &workos.AuditLogsUpdateOrganizationAuditLogsRetentionParams{
		RetentionPeriod: "1_MONTH",
	})
	if err != nil {
		panic(err)
	}
}
```

```php language="php" title="Request" tab="1"
<?php

// workos:manual - preserve the retention enum argument
use WorkOS\WorkOS;

$workos = new WorkOS(
    apiKey: "sk_example_123456789",
    clientId: "client_123456789",
);

$workos
    ->auditLogs()
    ->updateOrganizationAuditLogsRetention(
        id: "org_01EHZNVPK3SFK441A1RGBFSHRT",
        retentionPeriod: "1_MONTH",
    );
```

```java language="java" title="Request" tab="1"
// workos:manual - preserve the retention enum argument
import com.workos.WorkOS;
import com.workos.auditlogs.AuditLogsApi.UpdateOrganizationAuditLogsRetentionOptions;

WorkOS workos = new WorkOS("sk_example_123456789");

UpdateOrganizationAuditLogsRetentionOptions options =
    UpdateOrganizationAuditLogsRetentionOptions.builder()
        .retentionPeriod("1_MONTH")
        .build();

workos.auditLogs.updateOrganizationAuditLogsRetention(
    "org_01EHZNVPK3SFK441A1RGBFSHRT", options);
```

```cs language="dotnet" title="Request" tab="1"
// workos:manual - preserve the retention enum argument
using WorkOS;

var client = new WorkOSClient(new WorkOSOptions {
    ApiKey = "sk_example_123456789",
    ClientId = "client_123456789",
});

await client.AuditLogs.UpdateOrganizationAuditLogsRetentionAsync(
    "org_01EHZNVPK3SFK441A1RGBFSHRT", new AuditLogsUpdateOrganizationAuditLogsRetentionOptions {
        RetentionPeriod = "1_MONTH",
    });
```

```rust language="rust" title="Request" tab="1"
// workos:manual - preserve the retention enum argument
use workos::Client;
use workos::audit_logs::UpdateOrganizationAuditLogsRetentionParams;

#[tokio::main]
async fn main() -> Result<(), workos::Error> {
    let client = Client::builder()
        .api_key("sk_example_123456789")
        .client_id("client_123456789")
        .build();

    let _result = client
        .audit_logs()
        .update_organization_audit_logs_retention(
            "org_01EHZNVPK3SFK441A1RGBFSHRT",
            UpdateOrganizationAuditLogsRetentionParams {
                retention_period: "1_MONTH".into(),
                ..Default::default()
            }
        )
        .await?;

    Ok(())
}
```

```json language="json" title="Response" tab="2"
{
  "retention_period_in_days": 30
}
```

:::

### retention

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `retention_period_in_days` | number | Yes | The number of days Audit Log events will be retained before being permanently deleted. Valid values are `30` through `330` in 30-day increments and `365` through `3650` in 365-day increments. |

### GET /organizations/{id}/audit_logs_retention

#### Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | Unique identifier of the Organization. |

#### Returns

| Field | Type | Description |
| --- | --- | --- |
| `retention_period_in_days` | integer | The number of days Audit Log events will be retained. |

### PUT /organizations/{id}/audit_logs_retention

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `retention_period` | "1_MONTH" \| "2_MONTHS" \| "3_MONTHS" \| ... | No | The period Audit Log events will be retained. This is the recommended way to set retention. Valid values are `1_MONTH` through `11_MONTHS` in one-month increments and `1_YEAR` through `10_YEARS` in one-year increments. Exactly one of `retention_period` or `retention_period_in_days` must be provided. |
| `retention_period_in_days` | integer | No | The number of days Audit Log events will be retained. Valid values are `30` through `330` in 30-day increments and `365` through `3650` in 365-day increments. Deprecated in requests: use `retention_period` instead. |

#### Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | Unique identifier of the Organization. |

#### Returns

| Field | Type | Description |
| --- | --- | --- |
| `retention_period_in_days` | integer | The number of days Audit Log events will be retained. Valid values are `30` through `330` in 30-day increments and `365` through `3650` in 365-day increments. Deprecated in requests: use `retention_period` instead. |