Usage Tracking API

Plan usage monitoring and tier limit enforcement

Overview

The usage tracking system monitors creator activity against tier limits and enforces subscription boundaries server-side.

GET /api/usage

Retrieve usage statistics for authenticated user.

Authentication

Requires Directus JWT token.

Response

tier · string

Current pricing tier: starter, creator, pro, or studio

limits · object

Tier limits for all tracked operations

usage · object

Current usage counts for billing period

remaining · object

Remaining capacity (limit - usage) for each operation

Example

cURL

curl http://localhost:3001/api/usage \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Example Response

{
  "tier": "creator",
  "limits": {
    "posts_ai_assisted": 30,
    "posts_published": 90,
    "scheduled_queue_size": -1,
    "platforms_connected": 3,
    "taxonomy_ai_calls": 75,
    "watermark_ops": -1,
    "ai_clip_ops": 10,
    "thumbnail_ops": -1,
    "team_seats": 1
  },
  "usage": {
    "posts_ai_assisted": 12,
    "posts_published": 45,
    "taxonomy_ai_calls": 23,
    "ai_clip_ops": 3
  },
  "remaining": {
    "posts_ai_assisted": 18,
    "posts_published": 45,
    "taxonomy_ai_calls": 52,
    "ai_clip_ops": 7
  }
}

POST /api/usage/increment

Increment usage counter for a specific operation.

Authentication

Requires Directus JWT token or shared secret.

Request Body

operation · string · required

Operation name (e.g., posts_ai_assisted, taxonomy_ai_calls)

amount · number

Increment amount (default: 1)

Response

ok · boolean

Whether increment succeeded

newValue · number

Updated usage count

limitReached · boolean

Whether user has hit tier limit

Example

cURL

curl -X POST http://localhost:3001/api/usage/increment \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "operation": "posts_ai_assisted",
    "amount": 1
  }'

Example Response

{
  "ok": true,
  "newValue": 13,
  "limitReached": false
}

Tracked Operations

Operation Keys

Key	Description	Limit Type
posts_ai_assisted	AI caption/post generation	Monthly
posts_published	Cross-platform publishing	Monthly
scheduled_queue_size	Pending scheduled posts	Concurrent
platforms_connected	Active platform connections	Concurrent
taxonomy_ai_calls	Content classification calls	Monthly
watermark_ops	Image/video watermarking	Monthly
ai_clip_ops	Video teaser generation	Monthly
thumbnail_ops	Thumbnail extraction	Monthly
team_seats	Team member accounts	Concurrent

Limit Value Convention

• Positive number: Hard limit enforced
• -1: Unlimited (no enforcement)
• 0: Feature disabled for tier

Usage Reset Schedule

Monthly counters reset on the 1st of each month at 00:00 UTC:

• posts_ai_assisted
• posts_published
• taxonomy_ai_calls
• watermark_ops
• ai_clip_ops
• thumbnail_ops

Concurrent counters track current state (no reset):

• scheduled_queue_size
• platforms_connected
• team_seats

Enforcement Points

Usage limits enforced at:

1. API endpoints: /api/captions, /api/queue, /api/genie/stream-chat
2. Media worker: Job creation in media-worker/index.js
3. Dashboard UI: Proactive warnings before limit reached
4. Post scheduler: Queue size check before adding posts

Upgrade Prompts

When user hits limit:

{
  "error": "Usage limit reached",
  "operation": "posts_ai_assisted",
  "limit": 30,
  "current": 30,
  "upgradeUrl": "/pricing",
  "recommendedTier": "pro"
}

Dashboard shows upgrade banner with next tier benefits.

Implementation

Source: server/endpoints/api/usage.js

Usage data stored in user_personas collection:

• Fields: {operation}_used and {operation}_limit
• Server-side validation on every increment
• Atomic updates to prevent race conditions

Usage tracking is essential for monetization. All AI/media operations must call /api/usage/increment before execution.

Related Endpoints

Pricing Tiers

Detailed tier limits and pricing structure

User Profile

View and update user tier assignment