Scopix

Documentation

UsageResource

Access via client.usage - Usage monitoring, analytics, and plan utilization

Rate Limited

Usage endpoints are rate limited to 30 requests per minute, except check() which allows 60 requests per minute.

Credit & Limit Checks

check()

Check if an operation would exceed usage limits before attempting it.

python
async def check(
    *,
    analysis_level: str = "standard",
    item_count: int = 1,
    content_category: Optional[str] = None,
) -> UsageCheckResult

Example:

python
result = await client.usage.check(
    analysis_level="thorough", item_count=10
)
if result.can_proceed:
    print(f"Credits available: {result.available_credits}")
else:
    print(f"Limit reached: {result.message}")

get_breakdown()

Get credit usage breakdown for the current billing period.

python
async def get_breakdown() -> UsageBreakdown

Example:

python
breakdown = await client.usage.get_breakdown()
print(f"{breakdown.usage_percentage:.1f}% of monthly limit used")
print(f"Resets: {breakdown.reset_date}")

Usage Summary & Details

get_summary()

Get usage summary for a billing period including credits, request counts, limits, and plan info.

python
async def get_summary(
    *,
    start_date: Optional[datetime] = None,
    end_date: Optional[datetime] = None,
    period: str = "month",       # "day" | "week" | "month"
    api_key_id: Optional[str] = None,
) -> UsageSummary

Example:

python
summary = await client.usage.get_summary()
print(f"Credits used: {summary.total_credits}")
if summary.limits:
    print(f"Remaining: {summary.limits.remaining}")

get_details()

Get paginated usage event details with filtering support.

python
async def get_details(
    *,
    start_date: Optional[datetime] = None,
    end_date: Optional[datetime] = None,
    api_key_id: Optional[str] = None,
    operation_type: Optional[str] = None,
    limit: int = 50,
    offset: int = 0,
) -> UsageDetails

Example:

python
details = await client.usage.get_details(limit=20)
for event in details.events:
    print(f"{event.timestamp}: {event.endpoint} ({event.status_code})")

get_all_details()

Auto-paginating async iterator over all usage events.

python
async def get_all_details(
    *,
    start_date: Optional[datetime] = None,
    end_date: Optional[datetime] = None,
    api_key_id: Optional[str] = None,
    operation_type: Optional[str] = None,
    page_size: int = 50,
) -> AsyncIterator[UsageEvent]

Example:

python
async for event in client.usage.get_all_details():
    print(f"{event.timestamp}: {event.endpoint}")

Time Series & Analytics

get_by_period()

Get time series usage data grouped by period for charts and visualizations.

python
async def get_by_period(
    *,
    period_type: str = "day",    # "hour" | "day" | "month"
    start_date: Optional[datetime] = None,
    end_date: Optional[datetime] = None,
    api_key_id: Optional[str] = None,
) -> UsageByPeriod

Example:

python
daily = await client.usage.get_by_period(period_type="day")
for point in daily.data:
    print(f"{point.label}: {point.value}")

get_top_endpoints()

Get the most frequently used API endpoints ranked by request count.

python
async def get_top_endpoints(
    *,
    limit: int = 10,             # 1-50
    start_date: Optional[datetime] = None,
    end_date: Optional[datetime] = None,
) -> TopEndpoints

Example:

python
top = await client.usage.get_top_endpoints(limit=5)
for ep in top.endpoints:
    print(f"{ep.endpoint}: {ep.request_count} requests")

get_dashboard_analytics()

Get dashboard analytics with daily activity, token usage, and performance metrics.

python
async def get_dashboard_analytics(
    *,
    period: str = "month",       # "week" | "month" | "year"
) -> DashboardAnalytics

Example:

python
analytics = await client.usage.get_dashboard_analytics(period="week")
print(f"Files uploaded: {analytics.total_files_uploaded}")
print(f"Chat sessions: {analytics.total_chat_sessions}")
for day in analytics.daily_activity:
    print(f"  {day.date}: {day.files_uploaded} files, {day.chat_messages} messages")

Plan Utilization

get_plan()

Get comprehensive plan utilization with billing period, feature limits, usage projections, and optimization recommendations.

python
async def get_plan(
    *,
    period: str = "month",       # "month" | "quarter" | "year"
    include_projections: bool = True,
) -> PlanUtilization

Example:

python
plan = await client.usage.get_plan()
if plan.projections and plan.projections.will_exceed_limit:
    print("Warning: projected to exceed monthly limit")
if plan.plan_details:
    print(f"Plan: {plan.plan_details.plan_name}")
    print(f"Used: {plan.plan_details.usage_percentage:.1f}%")

Token Usage

get_monthly_tokens()

Get aggregated token usage over a date range. Defaults to the current billing period.

python
async def get_monthly_tokens(
    *,
    start_date: Optional[date] = None,   # date, not datetime
    end_date: Optional[date] = None,
) -> MonthlyTokenUsage

Example:

python
tokens = await client.usage.get_monthly_tokens()
print(f"Total tokens: {tokens.total_tokens:,}")
print(f"Input: {tokens.total_input_tokens:,}, Output: {tokens.total_output_tokens:,}")

get_file_tokens()

Get per-file token usage for processed files with pagination.

python
async def get_file_tokens(
    *,
    limit: int = 50,             # 1-100
    offset: int = 0,
) -> FileTokenUsageList

Example:

python
files = await client.usage.get_file_tokens(limit=10)
for f in files.files:
    print(f"{f.filename}: {f.total_tokens:,} tokens")

get_all_file_tokens()

Auto-paginating async iterator over all per-file token usage.

python
async def get_all_file_tokens(
    *,
    page_size: int = 50,
) -> AsyncIterator[FileTokenUsage]

Example:

python
async for f in client.usage.get_all_file_tokens():
    print(f"{f.filename}: {f.total_tokens:,} tokens")

get_conversation_tokens()

Get per-conversation token usage aggregated by chat session.

python
async def get_conversation_tokens(
    *,
    limit: int = 50,             # 1-100
    offset: int = 0,
) -> ConversationTokenUsageList

Example:

python
convos = await client.usage.get_conversation_tokens(limit=10)
for c in convos.conversations:
    print(f"{c.title}: {c.total_tokens:,} tokens ({c.message_count} messages)")

get_all_conversation_tokens()

Auto-paginating async iterator over all per-conversation token usage.

python
async def get_all_conversation_tokens(
    *,
    page_size: int = 50,
) -> AsyncIterator[ConversationTokenUsage]

Example:

python
async for c in client.usage.get_all_conversation_tokens():
    print(f"{c.title}: {c.total_tokens:,} tokens")

Sync Wrapper

SyncUsageResource

All methods are available synchronously via SyncScopix. Iterator methods (get_all_details, get_all_file_tokens, get_all_conversation_tokens) return regular Iterator instead of AsyncIterator.

python
from scopix import SyncScopix


client = SyncScopix(api_key="scopix_...")


# All the same methods, synchronously
breakdown = client.usage.get_breakdown()
print(f"{breakdown.usage_percentage:.1f}% used")


for event in client.usage.get_all_details():
    print(f"{event.timestamp}: {event.endpoint}")

Related

Usage Types

UsageCheckResult, UsageSummary, PlanUtilization, DashboardAnalytics, and more

Usage Analytics API Reference

REST API endpoint details and response schemas

Tenant Resource

Manage tenant settings and members