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

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. 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).

// 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).

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:

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:

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:

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 — Implements the retention configuration and pruning logic.
• .env.example — Documents the default value (REQUEST_ANALYTICS_RETENTION_DAYS=90).
• server/src/lib/request-log.ts — Imports pruneRequestAnalytics to schedule periodic cleanup.
• 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.
• 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 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, 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}