Scopix

Documentation

Usage Analytics API Reference

Monitor API usage, plan utilization, and performance metrics

Rate Limited

Usage analytics endpoints are rate limited to 30 requests per minute, except for the usage check endpoint which allows 60 requests per minute.

Usage Summary

GET/api/v2/usage/summary

Get aggregated usage statistics for the authenticated tenant. Supports filtering by date range, predefined period, or specific API key. Requires VIEW permission. Rate limit: 30/min.

Request

json
// Query parameters:
?start_date=2025-01-01T00:00:00Z   // optional - Start date for usage period
&end_date=2025-01-31T23:59:59Z     // optional - End date for usage period
&period=month                       // optional - Predefined period: day, week, month (default: month)
&api_key_id=uuid                    // optional - Filter by specific API key

Response

json
{
  "period": {
    "start": "2025-01-01T00:00:00Z",
    "end": "2025-01-31T23:59:59Z"
  },
  "usage": {
    "verify_count": 3500,
    "describe_count": 120,
    "total_requests": 3665,
    "successful_requests": 3600,
    "failed_requests": 65
  },
  "performance": {
    "avg_response_time_ms": 245.5
  },
  "limits": {
    "monthly_limit": 100000,
    "used_this_month": 3665,
    "remaining": 96335,
    "percentage_used": 3.67
  },
  "plan": {
    "name": "Professional",
    "requests_limit": 100000,
    "requests_used": 3665,
    "requests_remaining": 96335,
    "usage_percentage": 3.67,
    "renewal_date": "2025-01-31T23:59:59Z"
  },
  "total_credits": 4200
}
GET/api/v2/usage/details

Get individual usage event records with pagination for the authenticated tenant. Supports filtering by date range, API key, and operation type. Requires VIEW permission. Rate limit: 30/min.

Request

json
// Query parameters:
?start_date=2025-01-01T00:00:00Z   // optional - Start date for usage period
&end_date=2025-01-31T23:59:59Z     // optional - End date for usage period
&api_key_id=uuid                    // optional - Filter by specific API key
&operation_type=describe             // optional - Filter by operation type
&limit=50                            // optional - Items per page (default: 50, min: 1, max: 100)
&offset=0                            // optional - Items to skip (default: 0, min: 0)

Response

json
{
  "items": [
    {
      "id": "evt_abc123",
      "timestamp": "2025-01-15T14:30:00Z",
      "operation_type": "upload",
      "endpoint": "/api/v2/files/upload",
      "method": "POST",
      "status_code": 200,
      "response_time_ms": 312,
      "error_code": null,
      "api_key_id": "key_xyz789"
    }
  ],
  "total_count": 3665,
  "limit": 50,
  "offset": 0,
  "has_more": true
}
GET/api/v2/usage/by-period

Get usage data grouped by time period for charts and analytics. Returns time-series data points. Requires VIEW permission. Rate limit: 30/min.

Request

json
// Query parameters:
?period_type=day                     // optional - Period grouping: hour, day, month (default: day)
&start_date=2025-01-01T00:00:00Z    // optional - Start date
&end_date=2025-01-31T23:59:59Z      // optional - End date
&api_key_id=uuid                     // optional - Filter by API key

Response

json
{
  "period_type": "day",
  "start_date": "2025-01-01T00:00:00Z",
  "end_date": "2025-01-31T23:59:59Z",
  "data": [
    {
      "timestamp": "2025-01-01T00:00:00Z",
      "value": 125,
      "label": "2025-01-01"
    },
    {
      "timestamp": "2025-01-02T00:00:00Z",
      "value": 143,
      "label": "2025-01-02"
    }
  ]
}
GET/api/v2/usage/top-endpoints

Get the most frequently used endpoints ranked by request count. Useful for understanding API usage patterns. Requires VIEW permission. Rate limit: 30/min.

Request

json
// Query parameters:
?limit=10                            // optional - Number of top endpoints (default: 10, min: 1, max: 50)
&start_date=2025-01-01T00:00:00Z    // optional - Start date
&end_date=2025-01-31T23:59:59Z      // optional - End date

Response

json
{
  "endpoints": [
    {
      "endpoint": "/api/v2/files/upload",
      "operation_type": "upload",
      "request_count": 3500,
      "avg_response_time_ms": 280.3
    },
    {
      "endpoint": "/api/v2/chat/sessions",
      "operation_type": "chat",
      "request_count": 120,
      "avg_response_time_ms": 195.7
    }
  ]
}
GET/api/v2/usage/dashboard-analytics

Get dashboard analytics for visualizing activity over time. Returns daily activity breakdown, totals, and token usage for the specified period. Rate limit: 30/min.

Request

json
// Query parameters:
?period=month                        // optional - Period: "week", "month", or "year" (default: "month")

Response

json
{
  "period": "month",
  "start_date": "2025-01-01",
  "end_date": "2025-01-31",
  "daily_activity": [
    {
      "date": "2025-01-15",
      "files_uploaded": 45,
      "chat_messages": 12
    }
  ],
  "total_chat_messages": 420,
  "total_files_uploaded": 3500,
  "total_chat_sessions": 85,
  "avg_processing_time_ms": 245.5,
  "success_rate": 98.2,
  "processing_tokens": 170000,
  "chat_tokens": 117000,
  "total_tokens": 287000,
  "current_month_chat_tokens": 117000,
  "max_monthly_chat_tokens": 1000000
}

Credit Usage

POST/api/v2/usage/check

Check whether an operation would exceed usage limits before attempting it. Allows pre-flight validation of credit availability. Rate limit: 60/min.

Request

json
{
  "item_count": 1,                   // optional - Number of items to process (default: 1)
  "analysis_level": "standard",      // optional - Analysis level (default: "standard")
  "content_category": null           // optional - Content category to price the operation against (e.g. "blueprint", "ce_plan"); null uses default pricing
}

Response

json
{
  "can_proceed": true,
  "current_usage": 3665,
  "monthly_limit": 100000,
  "required_credits": 2,
  "available_credits": 96335,
  "reset_date": "2025-02-01",
  "message": null,
  "prepaid_credits": 0
}


// When limit exceeded:
{
  "can_proceed": false,
  "current_usage": 99999,
  "monthly_limit": 100000,
  "required_credits": 2,
  "available_credits": 1,
  "reset_date": "2025-02-01",
  "message": "Operation requires 2 credits, but only 1 available",
  "prepaid_credits": 0
}
GET/api/v2/usage/breakdown

Get a breakdown of credit usage for the current billing period. Shows totals, limits, and reset date. Rate limit: 30/min.

Response

json
{
  "current_month": "2025-01",
  "total_credits_used": 4200,
  "monthly_limit": 100000,
  "remaining_credits": 95800,
  "usage_percentage": 4.2,
  "reset_date": "2025-02-01T00:00:00+00:00"
}
GET/api/v2/usage/plan

Get comprehensive plan utilization and subscription information including billing period, feature limits, usage projections, and optimization recommendations. Requires VIEW permission. Rate limit: 30/min.

Request

json
// Query parameters:
?period=month                        // optional - Billing period: month, quarter, year (default: month)
&include_projections=true            // optional - Include usage projections and recommendations (default: true)

Response

json
{
  "billing_period": {
    "start_date": "2025-01-01T00:00:00Z",
    "end_date": "2025-01-31T23:59:59Z",
    "days_in_period": 31,
    "days_remaining": 16,
    "renewal_date": "2025-02-01T00:00:00Z"
  },
  "plan_details": {
    "plan_name": "Professional",
    "monthly_requests_limit": 100000,
    "requests_used": 3665,
    "requests_remaining": 96335,
    "usage_percentage": 3.67,
    "features": {
      "batch_processing": true,
      "priority_support": true,
      "agentic_chat": true
    }
  },
  "current_usage": {
    "total_requests": 3665,
    "by_service": {
      "upload": {
        "requests": 3500,
        "percentage": 95.5
      },
      "chat": {
        "requests": 120,
        "percentage": 3.3
      }
    }
  },
  "projections": {
    "projected_monthly_requests": 7500,
    "daily_average_requests": 244,
    "trending": "stable",
    "will_exceed_limit": false,
    "projected_usage_percentage": 7.5
  },
  "optimization_recommendations": {
    "suggestions": [
      {
        "type": "batch_upload",
        "message": "Consider using batch uploads for bulk processing to optimize throughput",
        "potential_request_savings": 500
      }
    ],
    "upgrade_recommendation": {
      "suggested": false,
      "reason": "Current usage is well within plan limits",
      "next_plan": "Enterprise",
      "benefits": ["Unlimited requests", "Dedicated support"]
    }
  }
}

Token Usage

GET/api/v2/usage/tokens/monthly

Get token usage totals for a date range. Defaults to the current billing period for paid tenants or calendar month for free tenants. Returns zero values if no data exists. Rate limit: 30/min.

Request

json
// Query parameters:
?start_date=2026-04-01               // optional - Start date (YYYY-MM-DD). Defaults to billing period start.
&end_date=2026-04-30                 // optional - End date (YYYY-MM-DD). Defaults to today.

Response

json
{
  "start_date": "2026-04-01",
  "end_date": "2026-04-30",
  "total_input_tokens": 210000,
  "total_output_tokens": 77000,
  "total_thinking_tokens": 15000,
  "total_tokens": 302000
}
GET/api/v2/usage/tokens/files

Get per-file token usage for processed files. Returns token counts for each file that has been processed with auto-describe, sorted by most recent first. Rate limit: 30/min.

Request

json
// Query parameters:
?limit=50                            // optional - Maximum files to return (default: 50, min: 1, max: 100)
&offset=0                            // optional - Offset for pagination (default: 0, min: 0)

Response

json
{
  "items": [
    {
      "image_id": "img_abc123",
      "filename": "product-photo.jpg",
      "input_tokens": 1200,
      "output_tokens": 450,
      "thinking_tokens": 150,
      "total_tokens": 1800,
      "created_at": "2025-01-15T14:30:00Z"
    }
  ],
  "total_count": 3500,
  "limit": 50,
  "offset": 0,
  "has_more": true,
  "total_input_tokens": 125000,
  "total_output_tokens": 45000,
  "total_thinking_tokens": 9000
}
GET/api/v2/usage/tokens/conversations

Get per-conversation token usage aggregated by chat session. Only includes sessions with token usage, sorted by most recent first. Rate limit: 30/min.

Request

json
// Query parameters:
?limit=50                            // optional - Maximum conversations to return (default: 50, min: 1, max: 100)
&offset=0                            // optional - Offset for pagination (default: 0, min: 0)

Response

json
{
  "items": [
    {
      "session_id": "sess_abc123",
      "title": "Product Analysis Discussion",
      "input_tokens": 5200,
      "output_tokens": 3100,
      "total_tokens": 8300,
      "message_count": 12,
      "created_at": "2025-01-15T10:00:00Z"
    }
  ],
  "total_count": 420,
  "limit": 50,
  "offset": 0,
  "has_more": true,
  "total_input_tokens": 85000,
  "total_output_tokens": 32000
}

Related

Rate Limits

API rate limiting details

SDK Usage Resource

Python SDK methods for usage monitoring and analytics

SDK Usage Types

UsageCheckResult, UsageSummary, PlanUtilization, DashboardAnalytics