GET /api/v1/cron/export-interactions
Exports new interaction history rows for all active tenants as Hive-partitioned NDJSON files. Uses checkpoint tracking to export only rows created since the last run.
Intended to be called by a cron scheduler (e.g., Vercel Cron Jobs, Kubernetes CronJob). Processes up to 10,000 rows per tenant per invocation.
Authentication
Requires a CRON_SECRET token via either:
Authorization: Bearer <CRON_SECRET> headerX-Cron-Secret: <CRON_SECRET> header
File Layout
exports/{tenantId}/interaction_history/year=YYYY/month=MM/day=DD/batch-{timestamp}.json
Response
{
"ok": true,
"totalExported": 8500,
"tenants": [
{
"tenantId": "tenant_001",
"tenantName": "Acme Corp",
"exported": 5200,
"filePath": "exports/tenant_001/interaction_history/year=2026/month=03/day=30/batch-2026-03-30T02-00-00-000Z.json"
},
{
"tenantId": "tenant_002",
"tenantName": "Beta Inc",
"exported": 3300,
"filePath": "exports/tenant_002/interaction_history/year=2026/month=03/day=30/batch-2026-03-30T02-00-01-000Z.json"
}
]
}
Error Handling
If export fails for one tenant, other tenants continue processing. Failed tenants include an error field and their checkpoint is marked as failed for retry on the next run.
In production, replace the local filesystem writes with S3 uploads via @aws-sdk/client-s3. The file paths follow the same Hive-style partitioning scheme.
GET /api/v1/cron/cleanup
Periodic data cleanup that removes expired suppressions and old daily summary rows. Also ensures future database partitions exist.
Authentication
Same as export: requires CRON_SECRET via Authorization or X-Cron-Secret header. If CRON_SECRET is not set in environment, the endpoint is open (development mode).
Cleanup Operations
| Operation | Description |
|---|
| Expired suppressions | Deletes rows from suppressions where expiresAt < NOW() |
| Old daily summaries | Deletes interaction_summaries with periodType = 'daily' older than 365 days |
| Partition maintenance | Creates database partitions for the next 3 months (non-fatal if partitions are not configured) |
Response
{
"status": "ok",
"cleaned": {
"expiredSuppressions": 45,
"oldDailySummaries": 1200,
"partitionsEnsured": 1
},
"timestamp": "2026-03-30T02:00:00.000Z"
}
Error Codes
| Code | Reason |
|---|
401 | Invalid or missing CRON_SECRET |
500 | Cleanup operation failed |
Environment Variables
| Variable | Required | Description |
|---|
CRON_SECRET | Recommended | Shared secret for authenticating cron requests |
Schedule these endpoints to run on a regular cadence:
- export-interactions: Every hour or every 6 hours depending on data volume
- cleanup: Once daily (e.g.,
0 3 * * *)
