Retention Management

Retention management controls how session recordings and certificates are stored, converted, and cleaned up over time. Each plan includes a monthly retention quota, and you can configure auto-retention behavior, overage alerts, and MP4 conversion.

Plan-based quotas

Your monthly retention quota depends on your plan tier:

Plan	Monthly retentions included	Overage rate
Starter ($199/mo)	1,000	$0.12 to $0.064 per certificate
Growth ($750/mo)	10,000	$0.12 to $0.064 per certificate
Enterprise ($1,500/mo)	Up to 50,000	$0.12 to $0.064 per certificate
High Volume (Custom)	50,000+	Custom

Overage rates decrease at higher volumes.

Auto-retention settings

Auto-retention controls whether session recordings are automatically stored and counted against your retention quota.

Setting	Type	Description
autoRetentionEnabled	boolean	Whether auto-retention is active
autoRetentionMode	string	all (retain all sessions) or certificates (retain only sessions that generated a certificate)
notifyOnOverage	boolean	Send email alerts when quota is exceeded
overageNotificationEmails	array	List of email addresses to receive overage alerts

Configuring auto-retention

Dashboard

1. Navigate to Settings > Retention in your dashboard at app.econsent.org.
2. Toggle Auto-Retention on or off.
3. Select the retention mode:
   • All Sessions: Retains every session recording, whether or not a certificate was generated.
   • Certificates Only: Retains only sessions that resulted in a certificate. This is more efficient for quota usage.
4. Enable Overage Notifications and add email addresses to receive alerts.
5. Save.

API

curl -X PUT https://api.econsent.org/api/retention/settings \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -d '{
    "autoRetentionEnabled": true,
    "autoRetentionMode": "certificates",
    "notifyOnOverage": true,
    "overageNotificationEmails": ["admin@example.com", "compliance@example.com"]
  }'

Tip

If you are on a limited plan, use certificates mode to retain only sessions with generated certificates. This avoids counting browsing-only sessions (where the user did not submit a form) against your quota.

API endpoints

eConsent provides two sets of retention endpoints: public API endpoints for programmatic retention from your backend, and dashboard endpoints used by the eConsent dashboard (authenticated via session).

Public API: Retain a session

Use this endpoint from your backend to retain a session recording. This stores the rrweb recording data so it remains available beyond the default expiration window. Your wallet is charged the session retention cost.

POST https://api.econsent.org/verify/session/:company_id

curl -X POST https://api.econsent.org/verify/session/YOUR_COMPANY_ID \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -d '{
    "session_id": "session-123"
  }'

Public API: Retain a certificate

Use this endpoint to retain a certificate and its associated session recording. Your wallet is charged the certificate retention cost.

POST https://api.econsent.org/verify/certificate/:company_id

curl -X POST https://api.econsent.org/verify/certificate/YOUR_COMPANY_ID \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -d '{
    "session_id": "session-123"
  }'

---

Dashboard endpoints

These endpoints are used by the eConsent dashboard and require authenticated session credentials. They are documented here for reference if you are building custom integrations against the dashboard API.

Single session retention

POST https://api.econsent.org/api/retention/convert

Retains a single session recording (MP4 conversion and permanent storage).

Batch retention

POST https://api.econsent.org/api/retention/convert-batch

Retains up to 100 sessions in a single request.

Note

Batch retention accepts a maximum of 100 session IDs per request. For larger batches, make multiple API calls.

Check quota status

GET https://api.econsent.org/api/retention/quota

Returns your current month’s quota usage:

{
  "plan": "growth",
  "quota": 10000,
  "used": 7523,
  "remaining": 2477,
  "period": "2026-04",
  "overage": false
}

Get detailed statistics

GET https://api.econsent.org/api/retention/stats

Returns a detailed breakdown of retention usage by property, including session counts, certificate counts, and storage metrics.

Update auto-retention settings

PUT https://api.econsent.org/api/retention/settings

Update auto-retention configuration. Available fields:

Field	Type	Description
autoRetentionEnabled	boolean	Enable or disable auto-retention
autoRetentionMode	string	"all" to retain every session, or "certificates" to retain only sessions with a generated certificate

Session lifecycle

Sessions follow this lifecycle:

1. Created. A new session is created when the tracker initializes on a page.
2. Recording. DOM events are captured and streamed to the eConsent API.
3. Certified. If the user submits a form with consent elements, a certificate is generated and linked to the session.
4. Retained. Based on auto-retention settings, the session recording is either retained (counted against quota) or discarded.
5. Expired. After the configured expiration period (7 days to 5 years), the session is marked for cleanup.
6. Cleaned up. A scheduled cron job removes expired sessions from storage.

Expiration settings

Session and certificate expiration are configured per property:

Duration	Use case
7 days	Testing and development
30 days	Short-term campaigns
60 days	Standard campaigns
1 year	Extended compliance
3 years	Long-term retention
5 years	Maximum retention for litigation protection

See Properties & Domains for details on configuring expiration per property.

Overage handling

When you exceed your plan’s monthly retention quota:

1. If notifyOnOverage is enabled, email alerts are sent to the addresses in overageNotificationEmails.
2. Additional retentions are billed at the overage rate ($0.12 to $0.064 per certificate, decreasing with volume).
3. Overage charges are deducted from your wallet balance.
4. Service continues uninterrupted as long as your wallet has sufficient funds.

Caution

Ensure your wallet has sufficient funds or enable auto-recharge to prevent service interruptions when exceeding your retention quota. Monitor usage from Billing > Usage in your dashboard.

Next steps

• Properties & Domains. Configure per-property expiration settings
• Session Replay. How session recordings are captured and stored
• Pricing & Billing. Plan details and overage pricing
• Revocation & Opt-Out. Consumer consent revocation