Plan

The plan endpoint returns your organization’s current plan tier, usage counters against each limit, and any pending downgrade information. Read-only for API clients — plan changes happen via Polar checkout, not the v1 API.

Get current limits

curl https://api.thefaq.app/api/v1/acme/plan/limits \
  -H "Authorization: Bearer $FAQAPP_API_KEY"

Response:

{
  "data": {
    "plan": "starter",
    "limits": {
      "apiRequestsPerMonth": 10000,
      "apiKeys": 5,
      "questions": 500,
      "organizations": 1,
      "members": 5,
      "customDomains": 0
    },
    "usage": {
      "apiRequestsThisMonth": 4218,
      "apiKeys": 2,
      "questions": 187,
      "members": 3
    },
    "billingPeriod": {
      "start": "2026-05-01T00:00:00Z",
      "end": "2026-06-01T00:00:00Z"
    },
    "renewal": "2026-06-01T00:00:00Z"
  }
}

Plan tiers: free, starter, pro, enterprise.

Required scope: any (read works).

Behavior at limit

When usage[X] hits limits[X]:

• Read endpoints keep serving but include a x-faq-soft-cap: true header
• Write endpoints return 402 plan_limit_reached with the limit name in the error details
• No automatic upgrade — you decide via Polar checkout when to raise the cap

Downgrade behavior

When you downgrade to a lower tier and your org is over the new tier’s limits, a cleanup job runs automatically to bring you back to compliance. You don’t have to do anything; you’ll see the cleanup result in the dashboard within a few minutes of the downgrade landing.

Error codes

• plan_limit_reached (402): a write was blocked because usage hit the cap; see error details for which limit