Skip to main content

​
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"

{
  "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
  }'

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

​
Tracked Operations

​
Operation Keys

KeyDescriptionLimit Type
posts_ai_assistedAI caption/post generationMonthly
posts_publishedCross-platform publishingMonthly
scheduled_queue_sizePending scheduled postsConcurrent
platforms_connectedActive platform connectionsConcurrent
taxonomy_ai_callsContent classification callsMonthly
watermark_opsImage/video watermarkingMonthly
ai_clip_opsVideo teaser generationMonthly
thumbnail_opsThumbnail extractionMonthly
team_seatsTeam member accountsConcurrent

​
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.

Pricing Tiers

Detailed tier limits and pricing structure

User Profile

View and update user tier assignment

Build docs developers (and LLMs) love

Get started for freeTalk to us