Endpoint: Usage Analytics

Track request volume, success rates, per-subscription breakdowns, and export historical usage data for billing and capacity planning.

Authentication

All usage analytics endpoints require session-based authentication. The authenticated user must hold one of these roles:

Role	Access
`SUPER_ADMIN`	Full access across all companies
`ACCOUNT_OWNER`	Company-scoped access
`SYNTHETIC_ADMIN`	Company-scoped access

Requests from users without these roles receive 403 Insufficient permissions.

GET /api/v1/usage

Retrieve aggregated usage statistics for routing advisory subscriptions within a time window.

Query Parameters

Parameter	Type	Required	Default	Description
`subscriptionId`	`string`	No	—	Filter to a specific subscription. Must belong to the caller's company.
`timeRange`	`string`	No	`day`	Aggregation window. One of: `hour`, `day`, `week`, `month`.
`includeDetails`	`string`	No	`false`	Set to `true` to include hourly distribution and top API consumers.

Example Request

bash

curl https://app.veriprompt.tech/api/v1/usage?timeRange=week&includeDetails=true \
  -H "Authorization: Bearer YOUR_API_KEY"

Filter by subscription:

bash

curl "https://app.veriprompt.tech/api/v1/usage?subscriptionId=sub_abc123&timeRange=day" \
  -H "Authorization: Bearer YOUR_API_KEY"

Success Response

json

{
  "timeRange": "week",
  "period": {
    "start": "2026-03-17T10:00:00.000Z",
    "end": "2026-03-24T10:00:00.000Z"
  },
  "summary": {
    "totalRequests": 4821,
    "successfulRequests": 4756,
    "failedRequests": 65,
    "successRate": 98.65
  },
  "requestsByType": {
    "ROUTING_ADVICE": 3200,
    "PROVIDER_HEALTH": 1100,
    "COST_ESTIMATE": 521
  },
  "requestsBySubscriber": [
    {
      "subscriberId": "sub_abc123",
      "subscriberName": "Production App",
      "subscriptionTier": "PROFESSIONAL",
      "requests": 3100
    },
    {
      "subscriberId": "sub_def456",
      "subscriberName": "Staging Environment",
      "subscriptionTier": "STARTER",
      "requests": 1721
    }
  ],
  "hourlyDistribution": [
    { "hour": "2026-03-24T09:00:00.000Z", "requests": 142 },
    { "hour": "2026-03-24T08:00:00.000Z", "requests": 198 }
  ],
  "topConsumers": [
    {
      "subscriberId": "sub_abc123",
      "requestCount": 3100,
      "lastRequest": "2026-03-24T09:58:12.000Z"
    }
  ],
  "rateLimitStatus": {
    "requestsPerHour": { "limit": 500, "used": 142, "remaining": 358 },
    "requestsPerDay": { "limit": 5000, "used": 3100, "remaining": 1900 }
  }
}

Notes:

requestsBySubscriber is omitted when filtering by a specific subscriptionId.
hourlyDistribution and topConsumers are only included when includeDetails=true.
rateLimitStatus is only included when filtering by a specific subscriptionId.

Error Responses

Status	Body	Cause
`401`	`{ "error": "Authentication required" }`	No active session
`403`	`{ "error": "Insufficient permissions" }`	User role not authorized
`404`	`{ "error": "Subscription not found or access denied" }`	`subscriptionId` does not exist or belongs to another company
`500`	`{ "error": "Failed to retrieve usage statistics" }`	Internal server error

GET /api/v1/usage/alerts

Retrieve active usage alerts and warnings for the caller's company subscriptions. Alerts are computed in real time based on current usage patterns and subscription state.

Alert Types

Type	Severity	Trigger
`USAGE_WARNING`	`WARNING`	Hourly usage reaches 80% of limit
`USAGE_CRITICAL`	`CRITICAL`	Hourly usage reaches 95% of limit
`DAILY_USAGE_WARNING`	`WARNING`	Daily usage reaches 80% of limit
`DAILY_USAGE_CRITICAL`	`CRITICAL`	Daily usage reaches 95% of limit
`SUBSCRIPTION_EXPIRY`	`WARNING` or `CRITICAL`	Subscription expires within 3 days (critical if within 1 day)
`SUBSCRIPTION_EXPIRED`	`CRITICAL`	Subscription has already expired
`UNUSUAL_ACTIVITY`	`WARNING`	Today's usage exceeds 3x the average daily usage from the prior week

Example Request

bash

curl https://app.veriprompt.tech/api/v1/usage/alerts \
  -H "Authorization: Bearer YOUR_API_KEY"

Success Response

json

{
  "alerts": [
    {
      "id": "usage_critical_sub_abc123",
      "type": "USAGE_CRITICAL",
      "severity": "CRITICAL",
      "subscriberId": "sub_abc123",
      "subscriberName": "Production App",
      "message": "Critical: Production App has used 478/500 requests this hour (96%)",
      "details": {
        "currentUsage": 478,
        "limit": 500,
        "utilizationPercent": 96,
        "timeWindow": "hour"
      },
      "createdAt": "2026-03-24T10:15:00.000Z"
    },
    {
      "id": "expiry_warning_sub_def456",
      "type": "SUBSCRIPTION_EXPIRY",
      "severity": "WARNING",
      "subscriberId": "sub_def456",
      "subscriberName": "Staging Environment",
      "message": "Staging Environment subscription expires in 2 days",
      "details": {
        "expiresAt": "2026-03-26T00:00:00.000Z",
        "daysRemaining": 2
      },
      "createdAt": "2026-03-24T10:15:00.000Z"
    },
    {
      "id": "unusual_activity_sub_abc123",
      "type": "UNUSUAL_ACTIVITY",
      "severity": "WARNING",
      "subscriberId": "sub_abc123",
      "subscriberName": "Production App",
      "message": "Unusual activity: Production App usage today (3200) is 4x higher than average",
      "details": {
        "todayUsage": 3200,
        "avgDailyLastWeek": 800,
        "multiplier": 4.0
      },
      "createdAt": "2026-03-24T10:15:00.000Z"
    }
  ],
  "summary": {
    "total": 3,
    "critical": 1,
    "warning": 2,
    "info": 0
  }
}

Alerts are sorted by severity (critical first), then by creation time (newest first).

Acknowledging Alerts

bash

curl -X POST https://app.veriprompt.tech/api/v1/usage/alerts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "alertId": "usage_critical_sub_abc123",
    "subscriberId": "sub_abc123"
  }'

Response:

json

{
  "success": true,
  "message": "Alert acknowledged"
}

Acknowledgments are recorded in the audit log for compliance tracking.

Error Responses

Status	Body	Cause
`401`	`{ "error": "Authentication required" }`	No active session
`403`	`{ "error": "Insufficient permissions" }`	User role not authorized
`400`	`{ "error": "Missing alertId and subscriberId" }`	POST body missing required fields
`404`	`{ "error": "Subscription not found" }`	Subscription does not belong to caller's company
`500`	`{ "error": "Failed to retrieve usage alerts" }`	Internal server error

GET /api/v1/usage/export

Export historical usage data as a CSV or JSON file download. Useful for billing reconciliation, capacity reports, and audit trails.

Query Parameters

Parameter	Type	Required	Default	Description
`startDate`	`string` (ISO 8601)	Yes	—	Start of the export window. Example: `2026-03-01T00:00:00Z`
`endDate`	`string` (ISO 8601)	Yes	—	End of the export window. Example: `2026-03-24T23:59:59Z`
`subscriptionId`	`string`	No	—	Filter to a specific subscription
`format`	`string`	No	`csv`	Output format: `csv` or `json`
`includeDetails`	`string`	No	`false`	Set to `true` to include client IP, user agent, and contact email

Constraints

Maximum date range: 90 days. Requests exceeding this limit receive 400.
Maximum records per export: 1,000 (most recent first).
startDate must be before endDate.

Example Request (CSV)

bash

curl -o usage_export.csv \
  "https://app.veriprompt.tech/api/v1/usage/export?startDate=2026-03-01T00:00:00Z&endDate=2026-03-24T23:59:59Z&format=csv" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Request (JSON with details)

bash

curl -o usage_export.json \
  "https://app.veriprompt.tech/api/v1/usage/export?startDate=2026-03-01T00:00:00Z&endDate=2026-03-24T23:59:59Z&format=json&includeDetails=true" \
  -H "Authorization: Bearer YOUR_API_KEY"

CSV Output Format

The response is served with Content-Type: text/csv and a Content-Disposition header for file download.

Standard columns:

Column	Description
`Timestamp`	ISO 8601 timestamp of the request
`Subscriber ID`	Unique subscription identifier
`Subscriber Name`	Human-readable subscription name
`Subscription Tier`	Tier level (e.g., STARTER, PROFESSIONAL, ENTERPRISE)
`Request Type`	Type of API request made
`Success`	`true` or `false`

Additional columns when includeDetails=true:

Column	Description
`Client IP`	Source IP address of the request
`User Agent`	Client user agent string
`Contact Email`	Subscription contact email

JSON Output Format

json

{
  "metadata": {
    "exportedAt": "2026-03-24T10:30:00.000Z",
    "exportedBy": "admin@company.com",
    "dateRange": {
      "start": "2026-03-01T00:00:00.000Z",
      "end": "2026-03-24T23:59:59.000Z"
    },
    "totalRecords": 847,
    "subscriptionId": "all"
  },
  "data": [
    {
      "timestamp": "2026-03-24T09:58:12.000Z",
      "subscriberId": "sub_abc123",
      "subscriberName": "Production App",
      "subscriptionTier": "PROFESSIONAL",
      "requestType": "ROUTING_ADVICE",
      "success": true,
      "clientIP": "203.0.113.42",
      "userAgent": "veriprompt-sdk/1.2.0",
      "contactEmail": "ops@company.com"
    }
  ]
}

clientIP, userAgent, and contactEmail fields are only present when includeDetails=true.

Error Responses

Status	Body	Cause
`400`	`{ "error": "startDate and endDate are required" }`	Missing date parameters
`400`	`{ "error": "Invalid date format. Use ISO 8601 format." }`	Unparseable date string
`400`	`{ "error": "startDate must be before endDate" }`	Inverted date range
`400`	`{ "error": "Date range cannot exceed 90 days" }`	Range too wide
`401`	`{ "error": "Authentication required" }`	No active session
`403`	`{ "error": "Insufficient permissions" }`	User role not authorized
`404`	`{ "error": "Subscription not found or access denied" }`	`subscriptionId` belongs to another company
`404`	`{ "error": "No usage data found for the specified criteria" }`	No records in the date range
`500`	`{ "error": "Failed to export usage data" }`	Internal server error

Endpoint: Usage Analytics ​

Authentication ​

GET /api/v1/usage ​

Query Parameters ​

Example Request ​

Success Response ​

Error Responses ​

GET /api/v1/usage/alerts ​

Alert Types ​

Example Request ​

Success Response ​

Acknowledging Alerts ​

Error Responses ​

GET /api/v1/usage/export ​

Query Parameters ​

Constraints ​

Example Request (CSV) ​

Example Request (JSON with details) ​

CSV Output Format ​

JSON Output Format ​

Error Responses ​

Related docs ​

Endpoint: Usage Analytics

Authentication

GET /api/v1/usage

Query Parameters

Example Request

Success Response

Error Responses

GET /api/v1/usage/alerts

Alert Types

Example Request

Success Response

Acknowledging Alerts

Error Responses

GET /api/v1/usage/export

Query Parameters

Constraints

Example Request (CSV)

Example Request (JSON with details)

CSV Output Format

JSON Output Format

Error Responses

Related docs