Prompt Logs API

Overview

The Prompt Logs feature tracks all prompts sent through the Veriprompt gateway with comprehensive metadata including prompt hash, provider details, sender information, and timestamps.

Database Schema

PromptLog Model

Field	Type	Description
id	String	Unique identifier (cuid)
promptId	String?	Reference to StoredPrompt if available
promptHash	String	SHA-256 hash of the sent prompt
providerName	String	Provider used (e.g., "OPENAI", "ANTHROPIC", "GOOGLE")
providerType	String	Provider type classification
modelName	String	Model used for the request
senderId	String?	User ID or API key ID that sent the request
senderType	String?	Sender classification: 'USER', 'API_KEY', 'SYSTEM'
companyId	String	Company that sent the prompt
timestamp	DateTime	When the prompt was sent
tokenCount	Int?	Total tokens used
executionId	String?	Link to AnonymousExecution record
ipAddress	String?	Request IP address
metadata	Json?	Additional context and metadata

Indexes

• timestamp - For time-based queries
• companyId, timestamp - Company-specific time queries
• promptHash - For duplicate detection
• senderId, timestamp - User-specific queries
• providerName, modelName - Provider analytics

API Endpoints

GET /api/admin/prompt-logs

Retrieve prompt logs with optional filtering.

Authentication: Required (session-based)

Query Parameters:

Parameter	Type	Required	Description
provider	string	No	Filter by provider name
senderId	string	No	Filter by sender ID
startDate	ISO date	No	Start date for filtering
endDate	ISO date	No	End date for filtering
limit	number	No	Maximum logs to return (default: 100)

Example Request:

GET /api/admin/prompt-logs?provider=OPENAI&limit=50&startDate=2025-01-01T00:00:00Z

Response:

{
  "success": true,
  "logs": [
    {
      "id": "log_abc123",
      "promptId": "prompt_xyz789",
      "promptHash": "a3f5d8b2c4e6f1a9b7c3d5e8f2a4b6c8d9e1f3a5b7c9d1e3f5a7b9c1d3e5f7a9b1",
      "providerName": "OPENAI",
      "providerType": "LLM_FOUNDATION",
      "modelName": "gpt-4o-mini",
      "senderId": "user_123",
      "senderType": "USER",
      "companyId": "company_456",
      "timestamp": "2025-10-16T08:30:00.000Z",
      "tokenCount": 1250,
      "executionId": "exec_1234567890_abc123",
      "ipAddress": "203.0.113.42",
      "metadata": {
        "systemPrompt": "present",
        "variableCount": 2,
        "attachmentCount": 0,
        "referencesResolved": false,
        "executionTimeMs": 1234
      }
    }
  ],
  "stats": [
    {
      "provider": "OPENAI",
      "count": 45,
      "totalTokens": 56780
    },
    {
      "provider": "ANTHROPIC",
      "count": 23,
      "totalTokens": 34120
    }
  ],
  "total": 68
}

Utility Functions

generatePromptHash(promptText: string): string

Generates a SHA-256 hash of the prompt text.

import { generatePromptHash } from '@/lib/prompt-logger';

const hash = generatePromptHash("What is the capital of France?");
// Returns: "a3f5d8b2c4e6f1a9b7c3d5e8f2a4b6c8d9e1f3a5b7c9d1e3f5a7b9c1d3e5f7a9b1"

logSentPrompt(data: PromptLogData): Promise<void>

Logs a sent prompt to the database.

import { logSentPrompt } from '@/lib/prompt-logger';

await logSentPrompt({
  promptId: 'prompt_123',
  promptText: 'What is the capital of France?',
  providerName: 'OPENAI',
  providerType: 'LLM_FOUNDATION',
  modelName: 'gpt-4o-mini',
  senderId: 'user_456',
  senderType: 'USER',
  companyId: 'company_789',
  tokenCount: 125,
  executionId: 'exec_abc123',
  ipAddress: '203.0.113.42',
  metadata: {
    systemPrompt: 'present',
    variableCount: 2
  }
});

getPromptLogs(params): Promise<PromptLog[]>

Retrieves prompt logs with filtering options.

import { getPromptLogs } from '@/lib/prompt-logger';

const logs = await getPromptLogs({
  companyId: 'company_123',
  providerName: 'OPENAI',
  startDate: new Date('2025-01-01'),
  endDate: new Date('2025-12-31'),
  limit: 100
});

Integration

The prompt logging is automatically integrated into the gateway execution flow at app/api/gateway/execute/route.ts:895-915. Every successful prompt execution is logged with:

• Prompt ID (if from stored prompt)
• SHA-256 hash of the actual sent prompt
• Provider and model information
• Sender details (user ID and type)
• Token usage
• Execution ID for cross-referencing
• IP address
• Additional metadata

Privacy & Security

• Hashing: Prompts are hashed using SHA-256 for duplicate detection without storing the actual prompt text
• IP Logging: IP addresses are captured for security auditing
• Access Control: Logs are company-scoped and require authentication
• GDPR Compliance: Logs respect company dataRetentionDays settings

Use Cases

1. Usage Analytics: Track which providers and models are most used
2. Cost Attribution: Link prompt usage to specific users or teams
3. Duplicate Detection: Identify repeated prompts via hash matching
4. Security Auditing: Monitor unusual patterns or suspicious activity
5. Performance Analysis: Correlate prompt characteristics with execution times
6. Billing & Reporting: Generate detailed usage reports per user/company

Archival & Retention

Retention Policy

Default: 90 days (configurable per company)

// Company model field
promptLogRetentionDays  Int  @default(90)

Recommended by Compliance:

• GDPR: 30-90 days (with business justification)
• SOC 2: 90-180 days
• PCI DSS: 90 days minimum
• HIPAA: 6 years (healthcare)
• Financial: 7 years (regulatory)

Admin Archival Functions

GET /api/admin/prompt-logs/archive

Get archival statistics:

{
  "success": true,
  "stats": {
    "totalLogs": 15000,
    "archivableCount": 3500,
    "oldestLog": "2024-09-01T00:00:00Z",
    "newestLog": "2025-01-15T23:59:59Z",
    "totalSizeEstimate": 3584000,
    "byProvider": [
      { "provider": "OPENAI", "count": 2100 },
      { "provider": "ANTHROPIC", "count": 1400 }
    ]
  },
  "retentionDays": 90
}

POST /api/admin/prompt-logs/archive

Actions: stats, export, archive, update-retention

Export Archive:

POST /api/admin/prompt-logs/archive
{
  "action": "export",
  "includePromptText": false
}
# Returns: JSON file download

Preview Archival (Dry Run):

POST /api/admin/prompt-logs/archive
{
  "action": "archive",
  "dryRun": true
}

Archive & Delete:

POST /api/admin/prompt-logs/archive
{
  "action": "archive",
  "exportFirst": true,
  "includePromptText": false
}

Update Retention Policy:

PATCH /api/admin/prompt-logs/archive
{
  "retentionDays": 180
}

Admin UI

Navigate to Admin → Prompt Log Management (/admin/prompt-log-management)

Features:

• View archival statistics
• Configure retention period (7-3650 days)
• Export logs to JSON
• Preview archival impact (dry run)
• Archive and delete old logs
• Provider breakdown charts

Workflow:

1. Review statistics
2. Export archive (JSON download)
3. Save archive to external storage (S3, etc.)
4. Delete old logs from database
5. Audit log automatically created

Automated Cleanup (Future)

For production deployments, schedule a cron job:

// Example: Daily cleanup at 2 AM
import { archiveAndDeleteLogs } from '@/lib/prompt-log-archival';

// Run for each company
const companies = await prisma.company.findMany();
for (const company of companies) {
  await archiveAndDeleteLogs(company.id, 'SYSTEM', {
    exportFirst: true
  });
}

Migration Notes

• Schema added: prompt_logs table
• Company field added: promptLogRetentionDays (default: 90)
• Indexes optimized for time-series queries
• Automatic logging added to gateway execution
• No impact on existing execution flow (non-blocking)
• Archival system ready for manual operation