# Data Retention Period for Request Analytics in FreeLLMAPI: Configuration and Defaults

> Configure the request analytics data retention period for FreeLLMAPI. Learn the default 90-day setting and how to adjust or disable it with the REQUEST_ANALYTICS_RETENTION_DAYS variable.

- Repository: [Tashfeen/freellmapi](https://github.com/tashfeenahmed/freellmapi)
- Tags: how-to-guide
- Published: 2026-06-25

---

**FreeLLMAPI retains request analytics data for 90 days by default, controlled entirely by the `REQUEST_ANALYTICS_RETENTION_DAYS` environment variable, which can be adjusted to any number of days or set to `0` to disable time-based pruning entirely.**

FreeLLMAPI stores every API request in a SQLite table named `requests` for analytics and monitoring purposes. The data retention period for request analytics in FreeLLMAPI is governed by a configurable environment variable defined in the source code, allowing operators to balance storage costs against historical analysis needs.

## Default Retention and Configuration Logic

The retention policy is implemented in [`server/src/services/request-retention.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/services/request-retention.ts). By default, the system keeps records for **90 days** unless explicitly overridden via environment configuration.

The `getRequestAnalyticsRetentionConfig()` function reads the `REQUEST_ANALYTICS_RETENTION_DAYS` environment variable using a `readNonNegativeInt` helper. If the variable is unset or empty, the code falls back to `DEFAULT_RETENTION_DAYS` (90).

```ts
// server/src/services/request-retention.ts
export function getRequestAnalyticsRetentionConfig(): RequestAnalyticsRetentionConfig {
  return {
    retentionDays: readNonNegativeInt('REQUEST_ANALYTICS_RETENTION_DAYS', DEFAULT_RETENTION_DAYS),
    maxRows: readNonNegativeInt('REQUEST_ANALYTICS_MAX_ROWS', DEFAULT_MAX_ROWS),
  };
}

```

## How the Pruning Mechanism Works

When the `pruneRequestAnalytics` routine executes, it translates the configured retention period into a timestamp cutoff. If `retentionDays` is greater than zero, the function deletes rows where the `created_at` column is older than the calculated cutoff date.

Setting `REQUEST_ANALYTICS_RETENTION_DAYS` to `0` disables time-based pruning entirely. In this mode, records persist indefinitely unless removed by the separate row-count limit (`REQUEST_ANALYTICS_MAX_ROWS`).

```ts
if (retentionDays > 0) {
  const cutoff = toSqliteTimestamp(new Date(nowMs - retentionDays * DAY_MS));
  deleted += db.prepare('DELETE FROM requests WHERE created_at < ?').run(cutoff).changes;
}

```

## Practical Configuration Examples

### Retrieving Current Retention Settings

Use the configuration getter to verify the active retention period at runtime:

```ts
import { getRequestAnalyticsRetentionConfig } from './server/src/services/request-retention.js';

const { retentionDays, maxRows } = getRequestAnalyticsRetentionConfig();
console.log(`Analytics are kept for ${retentionDays} days (max rows: ${maxRows})`);

```

### Running Manual Pruning

Administrators can force immediate cleanup regardless of the scheduled interval:

```ts
import { pruneRequestAnalytics } from './server/src/services/request-retention.js';

// Force pruning regardless of the regular interval
const result = pruneRequestAnalytics({ force: true });
console.log(`Deleted ${result.deleted} rows; skipped: ${result.skipped}`);

```

### Testing with Custom Retention Values

Override the retention period temporarily for testing or debugging:

```ts
process.env.REQUEST_ANALYTICS_RETENTION_DAYS = '30'; // keep only 30 days
import { pruneRequestAnalytics } from './server/src/services/request-retention.js';

pruneRequestAnalytics({ force: true });

```

## Key Source Files

The following files define and manage the retention behavior:

- **[`server/src/services/request-retention.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/services/request-retention.ts)** — Implements the retention configuration and pruning logic.
- **`.env.example`** — Documents the default value (`REQUEST_ANALYTICS_RETENTION_DAYS=90`).
- **[`server/src/lib/request-log.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/lib/request-log.ts)** — Imports `pruneRequestAnalytics` to schedule periodic cleanup.
- **[`server/src/__tests__/services/request-retention.test.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/__tests__/services/request-retention.test.ts)** — Contains tests confirming the 90-day default and pruning behavior.

## Summary

- **Default retention**: 90 days, defined by `DEFAULT_RETENTION_DAYS` in [`server/src/services/request-retention.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/services/request-retention.ts).
- **Configuration method**: Set the `REQUEST_ANALYTICS_RETENTION_DAYS` environment variable to any non-negative integer.
- **Disabling pruning**: Set the variable to `0` to keep analytics data indefinitely (subject to row limits).
- **Storage**: All request analytics reside in the SQLite `requests` table.
- **Execution**: The `pruneRequestAnalytics` function handles deletion based on the configured cutoff timestamp.

## Frequently Asked Questions

### What is the default data retention period for request analytics in FreeLLMAPI?

The default retention period is **90 days**. This value is hardcoded as `DEFAULT_RETENTION_DAYS` in [`server/src/services/request-retention.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/services/request-retention.ts) and applies when the `REQUEST_ANALYTICS_RETENTION_DAYS` environment variable is not set.

### How do I permanently disable automatic deletion of request analytics?

Set the environment variable `REQUEST_ANALYTICS_RETENTION_DAYS` to `0`. According to the logic in [`server/src/services/request-retention.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/services/request-retention.ts), a value of zero skips the time-based deletion logic, causing records to be retained indefinitely unless the optional row-count limit removes them.

### What controls the data retention period for request analytics in FreeLLMAPI?

The retention period is controlled by the **`REQUEST_ANALYTICS_RETENTION_DAYS`** environment variable. The `getRequestAnalyticsRetentionConfig()` function in [`server/src/services/request-retention.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/services/request-retention.ts) reads this variable and applies it to the pruning routine that deletes old records from the SQLite `requests` table.

### Does FreeLLMAPI enforce any other limits on analytics data besides time?

Yes. The system also supports a **`REQUEST_ANALYTICS_MAX_ROWS`** limit, which controls the maximum number of records stored in the `requests` table. When this limit is reached, older records are pruned regardless of the time-based retention setting.