Scopix

Documentation

Usage Types

Usage monitoring, analytics, and plan utilization types

Credit & Limit Check

UsageCheckResult

Result of a pre-flight usage limit check

python
@dataclass(frozen=True)
class UsageCheckResult:
    can_proceed: bool              # Whether the operation can proceed
    current_usage: int             # Credits used this period
    monthly_limit: int             # Total monthly credit limit
    required_credits: int          # Credits needed for this operation
    available_credits: int         # Credits remaining
    reset_date: Optional[str]      # When credits reset (YYYY-MM-DD)
    message: Optional[str]         # Human-readable status message
    prepaid_credits: int           # Prepaid credit balance

UsageBreakdown

Credit usage breakdown for the current billing period

python
@dataclass(frozen=True)
class UsageBreakdown:
    current_month: Optional[str]   # Current month (e.g. "2025-01")
    total_credits_used: int
    monthly_limit: int
    remaining_credits: int
    usage_percentage: float        # 0-100
    reset_date: Optional[str]      # ISO datetime

Usage Summary

UsageSummary

Aggregated usage summary for a billing period

python
@dataclass(frozen=True)
class UsageSummary:
    total_credits: int
    period: Optional[UsagePeriod]
    usage: Optional[UsageCounts]
    performance: Optional[UsagePerformance]
    limits: Optional[UsageLimits]
    plan: Optional[UsagePlan]

UsagePeriod

Billing period date range

python
@dataclass(frozen=True)
class UsagePeriod:
    start: Optional[str]           # ISO datetime
    end: Optional[str]

UsageCounts

Request counts within a usage summary

python
@dataclass(frozen=True)
class UsageCounts:
    verify_count: int
    describe_count: int
    total_requests: int
    successful_requests: int
    failed_requests: int

UsagePerformance

Performance metrics

python
@dataclass(frozen=True)
class UsagePerformance:
    avg_response_time_ms: float

UsageLimits

Usage limits and current consumption

python
@dataclass(frozen=True)
class UsageLimits:
    monthly_limit: int
    used_this_month: int
    remaining: int
    percentage_used: float         # 0-100

UsagePlan

Plan information within usage summary

python
@dataclass(frozen=True)
class UsagePlan:
    name: str                      # Plan name (e.g. "Professional")
    requests_limit: int
    requests_used: int
    requests_remaining: int
    usage_percentage: float
    renewal_date: Optional[str]
    prepaid_balance: int

Usage Details

UsageDetails

Paginated list of usage events

python
@dataclass(frozen=True)
class UsageDetails:
    events: list[UsageEvent]
    total_count: int
    limit: int
    offset: int
    has_more: bool

UsageEvent

A single API usage event

python
@dataclass(frozen=True)
class UsageEvent:
    id: str
    timestamp: Optional[str]
    operation_type: Optional[str]  # "describe", "verify", etc.
    endpoint: Optional[str]        # API path
    method: Optional[str]          # HTTP method
    status_code: Optional[int]
    response_time_ms: Optional[float]
    error_code: Optional[str]
    api_key_id: Optional[str]

Time Series

UsageByPeriod

Time series usage data grouped by period

python
@dataclass(frozen=True)
class UsageByPeriod:
    period_type: str               # "hour" | "day" | "month"
    start_date: Optional[str]
    end_date: Optional[str]
    data: list[TimeSeriesDataPoint]

TimeSeriesDataPoint

A single data point in a time series

python
@dataclass(frozen=True)
class TimeSeriesDataPoint:
    timestamp: Optional[str]
    value: float
    label: Optional[str]

TopEndpoints

List of most-used API endpoints

python
@dataclass(frozen=True)
class TopEndpoints:
    endpoints: list[TopEndpoint]

TopEndpoint

Usage statistics for a single endpoint

python
@dataclass(frozen=True)
class TopEndpoint:
    endpoint: str                  # API path
    operation_type: Optional[str]
    request_count: int
    avg_response_time_ms: float

Plan Utilization

PlanUtilization

Comprehensive plan utilization with projections and recommendations

python
@dataclass(frozen=True)
class PlanUtilization:
    billing_period: Optional[BillingPeriod]
    plan_details: Optional[PlanDetails]
    current_usage: Optional[CurrentUsage]
    projections: Optional[UsageProjection]
    optimization_recommendations: Optional[OptimizationRecommendations]

BillingPeriod

Billing period information

python
@dataclass(frozen=True)
class BillingPeriod:
    start_date: Optional[str]
    end_date: Optional[str]
    days_in_period: int
    days_remaining: int
    renewal_date: Optional[str]

PlanDetails

Plan details including features and limits

python
@dataclass(frozen=True)
class PlanDetails:
    plan_name: str
    monthly_requests_limit: int
    requests_used: int
    requests_remaining: int
    usage_percentage: float
    features: Optional[PlanFeatures]

PlanFeatures

Features included in the current plan

python
@dataclass(frozen=True)
class PlanFeatures:
    analysis_levels: list[str]     # Available analysis levels
    rule_sets_limit: int
    rule_sets_used: int
    batch_processing: bool
    priority_support: bool

CurrentUsage

Current usage broken down by service and analysis level

python
@dataclass(frozen=True)
class CurrentUsage:
    total_requests: int
    by_service: dict[str, ServiceBreakdown]
    by_analysis_level: dict[str, ServiceBreakdown]

ServiceBreakdown

Usage breakdown for a single service or analysis level

python
@dataclass(frozen=True)
class ServiceBreakdown:
    requests: int
    percentage: float              # 0-100

UsageProjection

Projected usage based on current trends

python
@dataclass(frozen=True)
class UsageProjection:
    projected_monthly_requests: int
    daily_average_requests: float
    trending: Optional[str]        # "stable" | "increasing" | "decreasing"
    will_exceed_limit: bool
    projected_usage_percentage: float

OptimizationRecommendations

Optimization recommendations with suggestions and upgrade info

python
@dataclass(frozen=True)
class OptimizationRecommendations:
    suggestions: list[OptimizationSuggestion]
    upgrade_recommendation: Optional[UpgradeRecommendation]

OptimizationSuggestion

A single optimization suggestion

python
@dataclass(frozen=True)
class OptimizationSuggestion:
    type: Optional[str]            # Suggestion category
    message: Optional[str]         # Human-readable recommendation
    potential_request_savings: int

UpgradeRecommendation

Plan upgrade recommendation

python
@dataclass(frozen=True)
class UpgradeRecommendation:
    suggested: bool
    reason: Optional[str]
    next_plan: Optional[str]
    benefits: list[str]

Token Usage

MonthlyTokenUsage

Aggregated token usage over a date range

python
@dataclass(frozen=True)
class MonthlyTokenUsage:
    start_date: Optional[str]
    end_date: Optional[str]
    total_input_tokens: int
    total_output_tokens: int
    total_thinking_tokens: int
    total_tokens: int

FileTokenUsageList

Paginated list of per-file token usage

python
@dataclass(frozen=True)
class FileTokenUsageList:
    files: list[FileTokenUsage]
    total_count: int
    total_input_tokens: int
    total_output_tokens: int
    total_thinking_tokens: int

FileTokenUsage

Token usage for a single processed file

python
@dataclass(frozen=True)
class FileTokenUsage:
    image_id: str
    filename: Optional[str]
    input_tokens: int
    output_tokens: int
    thinking_tokens: int
    total_tokens: int
    created_at: Optional[str]

ConversationTokenUsageList

Paginated list of per-conversation token usage

python
@dataclass(frozen=True)
class ConversationTokenUsageList:
    conversations: list[ConversationTokenUsage]
    total_count: int
    total_input_tokens: int
    total_output_tokens: int

ConversationTokenUsage

Token usage for a single chat session

python
@dataclass(frozen=True)
class ConversationTokenUsage:
    session_id: str
    title: Optional[str]
    input_tokens: int
    output_tokens: int
    total_tokens: int
    message_count: int
    created_at: Optional[str]

Dashboard Analytics

DashboardAnalytics

Dashboard analytics data for a period

python
@dataclass(frozen=True)
class DashboardAnalytics:
    period: str                         # "week" | "month" | "year"
    start_date: Optional[str]
    end_date: Optional[str]
    daily_activity: list[DailyActivity]
    total_chat_messages: int
    total_files_uploaded: int
    total_chat_sessions: int
    avg_processing_time_ms: Optional[float]
    success_rate: Optional[float]       # 0-100
    processing_tokens: int
    chat_tokens: int
    total_tokens: int
    current_month_chat_tokens: int
    max_monthly_chat_tokens: int

DailyActivity

A single day's activity data point

python
@dataclass(frozen=True)
class DailyActivity:
    date: Optional[str]            # YYYY-MM-DD
    files_uploaded: int
    chat_messages: int

Related

Usage Resource

Methods for monitoring usage, analytics, and plan utilization

Usage Analytics API Reference

REST API endpoint details and response schemas

Audit Types

AuditLogEntry, AuditLogList, AuditEventType