What Usage Tracking Does

Every billable action in ILLIXIS is tracked against your plan's monthly quota. Unlike platforms that surprise you with overage charges, ILLIXIS shows you usage in real time and requires explicit approval before billing any overage.

This system enforces soft caps — you can exceed your quota, but you must approve each overage transaction before it happens.

What Gets Tracked

Content Creation:

Briefs (Keyword, Trend, Custom, Calendar, Link Magnet)
Drafts (article generation)
Content extensions (expanding existing articles)
AI Images (hero images for articles)
Social Images (Quote Graphics, Twitter Threads, Carousels)
Infographics

Intelligence Operations:

Scans (opportunity discovery runs)
Gap reports (competitive gap analysis)
Trend scans (emerging topic discovery)
Brainstorms (AI ideation sessions)
Reports (executive reports)
Predictions (traffic forecasts)

Distribution & Marketing:

Email campaigns
Email sequences (active automation flows)
Social platforms (per-website connection limit)
Ad campaigns
Video scripts
AI videos (generated video assets)
Landing pages
Lead magnets (Quiz generation, Calculator generation, Assessment generation)

Quality & Optimization:

Originality checks (plagiarism detection — Pro+)
Fact-checks (citation verification — Pro+)

Analytics & AI:

Maya messages (tracked for engagement, no limits)

How Quotas Work

Monthly Reset: All usage counters reset on the 1st of each month. February 1st at 12:00 AM resets your brief count, social images, video scripts — everything except your connected social platforms (those are persistent connections, not monthly usage).

Overage Model: When you reach 100% of your quota, the platform blocks the action and shows you an approval modal:

"You've used all 30 briefs this month. Approve overage ($2.00 each) to continue?"

Until you click "Approve Overage," the operation does not proceed. This prevents surprise billing.

After approval:

The action completes
The overage counter increments
An approval record is created (audit trail)
At month-end, you're invoiced for all approved overages

Hard Caps vs Soft Caps: Most quotas are soft caps (overage allowed). Social Platforms is a hard cap — once you connect your tier's limit (4 for Starter, 8 for Professional, 13 for Enterprise), you cannot add more without upgrading.

Viewing Your Usage

Dashboard Widget: Your main dashboard shows a usage summary card:

Total quota across all categories
Current usage (percentage)
Overage count this month
Estimated overage charges (if any)

Settings → Usage & Billing: Full breakdown by quota type:

| Quota Type | Used | Quota | Remaining | Overage | Cost |
|------------|------|-------|-----------|---------|------|
| Briefs | 28 | 30 | 2 | 0 | $0.00 |
| Drafts | 50 | 50 | 0 | 3 | $30.00 |
| Social Images | 25 | 30 | 5 | 0 | $0.00 |

The "Cost" column shows overage charges for the current month.

Overage Pricing

Each quota type has a unit overage price set in your subscription plan. Common prices:

| Type | Overage Price |
|------|---------------|
| Briefs | $2.00 |
| Drafts | $10.00 |
| AI Images | $0.50 |
| Social Images | $0.25 |
| Video Scripts | $5.00 |
| AI Videos | $15.00 |
| Email Campaigns | $3.00 |
| Scans | $1.00 |

Prices vary by tier. Enterprise customers often negotiate custom overage rates.

Approval Workflow

Reaching 100% Quota: When you try to create a 31st brief (if your quota is 30):

Modal appears: "You've used all 30 briefs this month. Approve overage ($2.00 each) to continue?"
Two buttons: "Approve Overage" or "Cancel"
If you click Cancel, the operation aborts (no charge, no brief created)
If you click Approve, the brief generates and you're charged $2.00 at month-end

Approval Expiration: Overage approvals expire after 1 hour. If a background task tries to use an approval older than 1 hour, it fails and you must re-approve.

This prevents stale approvals from being reused across unrelated operations.

Audit Trail: Every approval creates a record with:

Who approved (user email)
When approved (timestamp)
What it was for (quota type)
Unit price at approval time (price lock)
What object was created (linked to the specific brief, content, etc.)

This audit trail ensures full transparency for billing disputes.

Trial Usage

Trial Limits: Trial users have enforced hard caps (no overage option):

| Type | Trial Limit |
|------|-------------|
| Briefs | 10 |
| Drafts | 5 |
| AI Images | 10 |
| AI Videos | 2 |
| Content Extensions | 3 |
| Email Sequences | 2 |

All other features are unlimited during trial to encourage exploration.

No Overage During Trial: Trial users cannot approve overages. When they hit the limit, they see:

"You have used all 5 drafts in your trial. Subscribe to get more."

This prevents surprise charges for trial users who don't yet have a payment method on file.

Beta Tenants

Beta tenants (marked with is_beta=True) have unlimited usage across all quotas. Usage is tracked for analytics, but no enforcement or billing occurs.

This is used for:

Internal testing
Early access partners
Lifetime grandfathered accounts

Fair-Use Ceilings

Some quotas have fair-use ceilings to prevent abuse:

Social Posts: Unlimited posts per month, but subject to fair-use ceilings:

Starter: 250 posts/month
Professional: 500 posts/month
Enterprise: 800 posts/month

Exceeding the ceiling triggers a review. Persistent abuse (automated spamming) may result in account suspension.

Monthly Billing

End-of-Month Process: On the last day of the month:

Overage charges are calculated for all accounts
A Stripe invoice is created for the total overage amount
The usage record is marked as billed
A billing record is created for the audit trail

Invoice Breakdown: Your Stripe invoice shows:
```
Subscription (Professional Plan) $2,497.00
Overage - Drafts (3 × $10.00) $30.00
Overage - AI Videos (2 × $15.00) $30.00
-------------------------------------------
Total $2,557.00
```

Each overage line item includes the quantity and unit price.

Automation Schedule

Usage tracking runs on automated schedules to ensure accurate billing and proactive alerts:

Daily Usage Aggregation (11:59 PM UTC):
All individual usage events from the day are consolidated into daily totals. This aggregation improves query performance and ensures your usage dashboard loads quickly even with high-volume accounts.

Monthly Usage Rollup (1st of month, 12:30 AM UTC):
On the first of each month, the previous month's usage is finalized and locked for billing. This creates the immutable usage record that appears on your invoice. The rollup runs 30 minutes after midnight to ensure all end-of-month operations complete first.

Usage Cost Calculation (Hourly):
Behind the scenes, ILLIXIS tracks the actual costs of your operations. These costs are recalculated hourly to provide accurate tracking. This data powers the platform's cost analytics but does not affect your billing -- you pay quota-based pricing, not cost passthrough.

Usage Anomaly Detection (6:00 AM UTC daily):
An automated scan checks for unusual usage patterns:

Sudden spikes (10x normal daily volume)
Unusual timing (bulk operations at 3 AM)
Pattern anomalies (same content generated repeatedly)

Anomalies trigger internal review but do not automatically affect your account. This protects against compromised credentials or runaway automation.

Quota Warning Emails (Threshold-based):
When you reach 80% of any quota, the system sends a warning email:

"You've used 24 of 30 briefs this month (80%). At your current pace, you'll exceed your quota by the 25th."

This gives you time to either slow down, approve overages in advance, or upgrade your plan before hitting the limit.

Common Scenarios

Scenario 1: High-Volume Content Month
You're a Starter subscriber (30 briefs/month). Black Friday is coming and you need 45 briefs.

What happens:

First 30 briefs: No overage
Brief 31-45: Each requires approval ($2.00 each)
End of month invoice: Base $997 + $30 overage = $1,027

Best practice: Approve overages in batches. Click "Approve Overage" once, generate 5 briefs back-to-back within the 1-hour approval window.

Scenario 2: Trial User Hits Limit
You're on a 7-day trial. You've created 5 drafts (the trial limit). You try to create a 6th.

What happens:
Modal appears: "You have used all 5 drafts in your trial. Subscribe to continue."

No "Approve Overage" button. You must upgrade to a paid plan to proceed.

Scenario 3: Social Platform Hard Cap
You're a Professional subscriber (8 social platforms per website). You've connected Twitter, LinkedIn, Facebook, Instagram, TikTok, YouTube, Pinterest, and Threads. You try to add Bluesky.

What happens:
Error: "You've reached your plan's social platform limit (8). Upgrade to Enterprise for unlimited platforms."

This is a hard cap. No overage option exists. You must upgrade or disconnect an existing platform.

Scenario 4: Month-End Overage Review
It's January 31st. You approved 10 overage briefs this month ($20 total). Your credit card on file is declined.

What happens:

Stripe attempts to charge the overage
Payment fails
Your subscription status changes to past_due
You receive an email: "Payment failed. Update payment method to avoid service interruption."
After 3 failed attempts (over 7 days), subscription cancels automatically

Best practice: Keep a valid payment method on file. Set up billing alerts in Stripe dashboard.

FAQ

Why does ILLIXIS require approval for overages instead of auto-billing?

Transparency and control. Many SaaS platforms surprise users with $500 overage charges. ILLIXIS requires explicit consent before any overage occurs.

Can I set a hard cap to prevent overages entirely?

Not yet. This feature is planned for a future release. For now, monitor your usage dashboard and decline overage approvals if you want to stay within quota.

What happens if I approve an overage but the task fails?

The overage is not charged. Overages only bill when the task completes successfully and creates the object (brief, content, etc.). If the task fails, the approval is discarded.

Do social posts count against a quota?

Social posts are unlimited (no quota). However, fair-use ceilings apply (250/500/800 depending on tier). Social platform connections (Twitter, LinkedIn, etc.) are limited by tier.

How do I see a history of my overage approvals?

Go to Settings → Usage & Billing → Overage History. You'll see a table of all approvals:

Date/time approved
User who approved
Quota type
Unit price
Object created (link to brief, content, etc.)

This audit trail is exportable as CSV for expense reporting.

Can I dispute an overage charge?

Yes. Email support@illixis.io with:

Invoice number
Disputed overage line item
Reason for dispute

Include the overage approval ID from the audit trail. All disputes are reviewed within 48 hours.

Does usage tracking work offline?

No. Usage tracking requires a live database connection to enforce quotas. If you're using ILLIXIS offline (localhost development), usage tracking is disabled.

What counts as a "Social Image" vs a regular "AI Image"?

AI Images (tracked under images quota): Hero images for articles (AI-generated for blog posts).

Social Images (tracked under social_images quota): Quote Graphics, Twitter Thread images, Carousel slides, and Infographics AI-generated for social media.

Separate quotas allow higher social image volume without consuming article image quota.

Related Features

Maya — Chief Growth Officer — Maya proactively alerts you when quota nears expiration
Subscription Management — Upgrade plans to increase quotas
Billing History — View past invoices and overage charges
Trial Onboarding — Understand trial limits before subscribing

Usage Tracking