Rate limits and plans

Platform API calls are metered per organization, not per token. Every Personal Access Token in an organization spends from the same budget, so adding tokens adds no capacity. This is the canonical page for the numbers.

What is an API credit?

An API credit is the unit Fomr uses to measure Platform API usage. Each call spends a fixed number of credits from your organization’s budget, whichever token makes it:

• Most calls cost 1 credit. Reading, creating, updating, publishing, and deleting all cost the same.
• Generating a form with AI costs 10 credits, because it runs an AI model.
• Checking your usage costs nothing, so you can always see where you stand. The public /v1/openapi.json and /v1/docs pages are free too.
• Failed calls cost nothing. If a call ends in an error, its credits are returned, so fixing a mistake and trying again never costs twice.

Your plan sets how many credits you can spend and how quickly. Credits are not money: you never buy them, and Fomr never bills you for them. When credits run out, calls pause until the budget refills, or, on Free, until you upgrade.

Examples

What you do	Calls	Credits
Check which organization a token belongs to	GET /v1/me	1
List your forms, 25 per page, when you have 60 forms	3 × GET /v1/forms	3
Read 250 submissions at the maximum page size of 100	3 × GET /v1/forms/{id}/submissions	3
Export every submission of a form as CSV, however many rows	1 × GET /v1/forms/{id}/submissions/export	1
Create a form, write its draft, validate it, and publish it	createForm, updateFormDraft, validateForm, publishForm	4
Generate a form with AI, then publish it	generateForm, publishForm	11
Check your remaining budget	GET /v1/usage	0

A credit is spent per call, not per item in the response. Asking for 100 submissions in one page costs the same as asking for one, so larger pages and exports save credits.

A Free organization has 100 credits per 24 hours. That covers, for example, a nightly job that exports submissions from 20 forms (20 credits) and publishes 15 forms built from your own blueprints (4 credits each, 60 credits), with 20 credits to spare. The same 100 credits cover ten AI generations and nothing else.

Two budgets

Every call must fit inside two budget policies at once.

	Free	Pro
API Burst pool	100 credits	10,000 credits
API Cooldown and refill length	24 hours	24 hours
API Minute Cap	60 credits per minute	300 credits per minute

• API Burst is a pool of credits. Spending the first credit opens a refill window of one cooldown length; if the pool is not used up, it refills when that window ends. Spending the last credit starts a full API Cooldown, measured from that moment, and the pool refills when the cooldown ends.
• API Minute Cap limits credits per fixed 60-second window. It has no cooldown; the window simply turns over.

For example, a Free organization that spends its first credit at 09:00 on Monday and never empties the pool gets a full pool again at 09:00 on Tuesday. If it spends its last credit at 15:00 on Monday, the cooldown runs until 15:00 on Tuesday.

The minute cap is checked first, so a call it rejects spends no burst credits. A call the burst rejects still counts toward the current minute. Rejected calls never extend or shorten a cooldown.

Credits and costs

Each call has a fixed API Request Cost, the same on every plan:

Call	Cost
Any Platform API call	1 credit
Generating a form with AI (generateForm)	10 credits
Reading usage (GET /v1/usage)	0 credits

The API reference lists the cost of every operation.

Only successful calls spend credits. A call is held against your budget while it runs, and if it ends in an error, any 4xx or 5xx answer, its credits are returned at once. A publish blocked by Publish Issues, a 404 for a form that does not exist, and an AI provider failure all cost nothing.

A failed call still counts toward the API Minute Cap, because that cap limits how fast a client calls, not what it spends.

A 10-credit call needs 10 credits free in both policies. When fewer remain, it is rejected and spends no burst credits, while 1-credit calls keep going through until the pool is empty.

RateLimit headers

Every authenticated response, successful or not, carries the current reading for both policies.

RateLimit-Policy: "burst";q=100;w=86400, "minute";q=60;w=60
RateLimit: "burst";r=63;t=79512, "minute";r=57;t=41

These follow the IETF RateLimit header fields draft (draft-11).

Parameter	Meaning
q	The limit — credits the policy allows in one window
w	The window length, in seconds
r	Credits remaining in the current window
t	Seconds until that window resets

RateLimit-Policy changes only when the plan changes. RateLimit is the live reading. The example is a Free organization with 63 of 100 burst credits left, about 22 hours before the pool refills, and 57 of 60 minute credits left for another 41 seconds.

A 429 also carries Retry-After, always in seconds, equal to the t of the policy that rejected the call. The Platform API sends no X-RateLimit-* headers.

Missing headers do not mean unlimited

If the RateLimit fields are missing, Fomr is briefly counting approximately. The budget still applies, and GET /v1/usage reports degraded: true. Keep pacing your client as before.

When a call is throttled

A call over budget gets a 429 Platform Error. Both throttle codes carry the same fields.

Field	What it holds
code	API_COOLDOWN or TOO_MANY_REQUESTS
message	A human-readable explanation. It is not part of the contract
request_id	The ID of this request, also sent as X-Request-Id
policy	burst or minute — which budget rejected the call
plan	The organization’s plan at the moment of the call
limit	That policy’s limit, in credits
used	Credits spent in the current window
remaining	Credits left in the current window
cost	What the rejected call would have cost
window_seconds	That policy’s window length
cooldown_until	When the API Cooldown ends, or null when there is no cooldown
resets_at	When the current window resets
retry_after_seconds	The same number as the Retry-After header
upgrade_url	The upgrade link on Free, or null on Pro

Branch on code, and on policy to tell the two TOO_MANY_REQUESTS cases apart.

API_COOLDOWN

The API Burst pool is empty and the organization is in an API Cooldown. Every call except GET /v1/usage is rejected until cooldown_until.

429 API_COOLDOWN

{
  "code": "API_COOLDOWN",
  "message": "This Free organization has spent its 100 Platform API credits and is in API Cooldown until 2026-10-02T09:00:00Z. Upgrade to Pro to lift the cooldown now.",
  "request_id": "0f3c2a9e-6b1d-4e57-9a1c-2d8e4f6b7c90",
  "policy": "burst",
  "plan": "free",
  "limit": 100,
  "used": 100,
  "remaining": 0,
  "cost": 1,
  "window_seconds": 86400,
  "cooldown_until": "2026-10-02T09:00:00.000Z",
  "resets_at": "2026-10-02T09:00:00.000Z",
  "retry_after_seconds": 79512,
  "upgrade_url": "https://fomr.io/app/upgrade?source=platform_api&feature=platform_api"
}

TOO_MANY_REQUESTS

cooldown_until is null: nothing is locked, a window just has to turn over.

policy: "minute" means the API Minute Cap was hit.

429 TOO_MANY_REQUESTS — policy "minute"

{
  "code": "TOO_MANY_REQUESTS",
  "message": "Pro organizations can spend 300 Platform API credits per minute. Retry in 17 seconds.",
  "request_id": "0f3c2a9e-6b1d-4e57-9a1c-2d8e4f6b7c90",
  "policy": "minute",
  "plan": "pro",
  "limit": 300,
  "used": 300,
  "remaining": 0,
  "cost": 1,
  "window_seconds": 60,
  "cooldown_until": null,
  "resets_at": "2026-10-01T09:01:00.000Z",
  "retry_after_seconds": 17,
  "upgrade_url": null
}

policy: "burst" means too few burst credits remain for this call, typically a 10-credit generation when the pool is nearly empty. 1-credit calls still succeed.

429 TOO_MANY_REQUESTS — policy "burst"

{
  "code": "TOO_MANY_REQUESTS",
  "message": "This call costs 10 credits; 3 remain until 2026-10-02T09:00:00Z.",
  "request_id": "0f3c2a9e-6b1d-4e57-9a1c-2d8e4f6b7c90",
  "policy": "burst",
  "plan": "free",
  "limit": 100,
  "used": 97,
  "remaining": 3,
  "cost": 10,
  "window_seconds": 86400,
  "cooldown_until": null,
  "resets_at": "2026-10-02T09:00:00.000Z",
  "retry_after_seconds": 79512,
  "upgrade_url": "https://fomr.io/app/upgrade?source=platform_api&feature=platform_api"
}

What to do about each

• TOO_MANY_REQUESTS, policy: "minute": wait Retry-After seconds (at most 60), then retry with bounded backoff.
• TOO_MANY_REQUESTS, policy: "burst": the call costs more than is left. Cheaper calls still work; this one waits for resets_at.
• API_COOLDOWN: stop until cooldown_until, or upgrade. Never retry in a loop.

Per-IP limit

Separately from the organization budget, each IP address can call one operation at most 600 times per minute, and generateForm at most 5 times per minute. Over that limit the API answers 429 TOO_MANY_REQUESTS with Retry-After and only the basic Platform Error fields, with no policy. These requests spend no credits. In practice you meet this limit only when generating more than five forms a minute, or when several organizations call from one IP address.

Changing plans

Each plan has its own counters.

• Upgrading to Pro lifts a Free cooldown immediately, because the Pro budget starts unused.
• Returning to Free before the Free window ends resumes the earlier Free counters, including any cooldown.

Reading your usage

GET /v1/usage (operation getUsage) reports where the organization stands right now. It spends no credits and works during a cooldown.

curl https://platform.fomr.io/v1/usage \
  -H "Authorization: Bearer $FOMR_TOKEN"

GET /v1/usage

{
  "plan": "free",
  "limits": {
    "max_forms": 3,
    "max_submissions_per_month": 100
  },
  "counts": {
    "forms": 2,
    "submissions_this_month": 17
  },
  "api": {
    "plan": "free",
    "burst": {
      "limit": 100,
      "used": 37,
      "remaining": 63,
      "window_seconds": 86400,
      "resets_at": "2026-10-02T09:00:00.000Z",
      "cooldown_until": null
    },
    "minute": {
      "limit": 60,
      "used": 3,
      "remaining": 57,
      "window_seconds": 60,
      "resets_at": "2026-10-01T09:01:00.000Z"
    },
    "costs": {
      "request": 1,
      "ai_generation": 10
    },
    "degraded": false
  }
}

• plan and limits are the organization’s plan and its plan limits.
• counts holds the organization’s forms and its submissions this month. counts.forms is the figure the plan’s form limit is checked against: every form that is not a Private Template, including forms in Trash, until they are permanently deleted.
• api.burst and api.minute are the live reading of each policy: limit, used, remaining, window_seconds, resets_at (null while nothing has been spent), and, on the burst, cooldown_until.
• api.costs holds the API Request Costs: request for an ordinary call and ai_generation for generateForm. Read them instead of hardcoding them.
• api.degraded is true while the numbers are approximate.

The same numbers appear in the app under Settings > API.

Staying inside the budget

• Read RateLimit on every response, not just on failures, and slow down before you hit a limit.
• Keep a steady pace. The minute cap is usually the first limit a client meets.
• Back off with a ceiling. Honour Retry-After, add jitter, and stop after a fixed number of attempts.
• Budget expensive calls. Ten form generations use a Free organization’s entire 100-credit pool. Check remaining before a batch.
• Coordinate your tokens. They share one budget, so two jobs running at full speed throttle each other. They also share the organization’s two submission export slots.