Appearance

Usage API ​

GET /api/usage returns how much of the plan a workspace has used this month: posts, connected accounts, X posts, X spend and storage. Call it before a big batch so an agent or script can stop early instead of hitting a 403.

Any workspace member can read it, and guarded API keys may call it. Auth is in the REST API overview.

How do I check my usage and remaining quota? ​

bash
curl https://api.socifyr.com/api/usage \
  -H "Authorization: Bearer sk_..."
json
{
  "success": true,
  "data": {
    "tier": "free",
    "uploads": { "used": 7, "limit": 30, "remaining": 23, "unlimited": false },
    "accounts": { "used": 2, "limit": 3, "remaining": 1, "unlimited": false },
    "xPosts": { "used": 1, "limit": 5, "remaining": 4, "unlimited": false },
    "xSpendUsd": 0.2,
    "storage": {
      "used": 52428800,
      "limit": 1073741824,
      "remaining": 1021313024,
      "unlimited": false,
      "usedBytes": 52428800,
      "limitBytes": 1073741824
    }
  }
}

The numbers above are an example on the Free plan limits from @socifyr/shared. Yours depend on your plan. See Limits for every tier.

FieldMeaning
tierfree, pro or business. The tier of the workspace owner.
uploadsPosts dispatched this month.
accountsActive connected accounts.
xPostsPosts to X this month against the plan's included allowance.
xSpendUsdEstimated X API spend this month, in US dollars.
storageMedia storage. used and usedBytes are bytes in use, limit and limitBytes are the cap.

For a dimension with no cap, limit and remaining are null and unlimited is true. Self-hosted installs report every dimension as unlimited.

What happens when I reach a limit? ​

Creating a post past the cap returns 403 with a plain message, for example Upload limit reached for your plan. Upgrade to continue. or X (Twitter) post allowance reached (5/month on your plan).... See Content API for the full error table.

Frequently asked questions ​

Does saving a draft use my monthly uploads? The counter increases when a post is dispatched for publishing, not when a draft is saved.

When do the monthly counters reset? The counters are monthly. The API returns the current counters and does not return a reset date.

Next steps ​