Skip to content
Fomr LogoFomr Help Center
Join our Slack

Read plan limits and API usage

GET
/v1/usage
curl --request GET \
  --url https://platform.fomr.io/v1/usage \
  --header 'Authorization: Bearer <token>'

Returns the plan, the plan limits, what the organization is using, and the live Platform API budget. Spends no API credits.

Authorizations

Section titled “Authorizations”

Responses

Section titled “Responses”

200

Section titled “200”

Default Response

Media typeapplication/json
object
plan
required

The effective subscription plan of the organization.

string
Allowed values: free pro
limits
required

The plan limits the counts below are measured against.

object
max_forms
required
Any of:
integer
>= -9007199254740991 <= 9007199254740991
max_submissions_per_month
required
Any of:
integer
>= -9007199254740991 <= 9007199254740991
counts
required

What the organization is using right now.

object
forms
required

The Plan Form Count: forms that are not Private Templates and have not been permanently deleted, including forms in Trash.

integer
>= -9007199254740991 <= 9007199254740991
submissions_this_month
required

Completed submissions received since the start of the current month, in UTC.

integer
>= -9007199254740991 <= 9007199254740991
api
required

The live Platform API budget state. Reading it spends nothing.

object
plan
required

The plan whose numbers the budget is running on right now.

string
Allowed values: free pro
burst
required

The API Burst policy and its live state.

object
limit
required

Credits the organization may spend before the API Cooldown starts.

integer
>= -9007199254740991 <= 9007199254740991
used
required

Credits spent in the window that is currently open.

integer
>= -9007199254740991 <= 9007199254740991
remaining
required

Credits left before the API Cooldown starts.

integer
>= -9007199254740991 <= 9007199254740991
window_seconds
required

How long the window lasts. The API Cooldown is the same length.

integer
>= -9007199254740991 <= 9007199254740991
resets_at
required
Any of:
string format: date-time
/^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$/
cooldown_until
required
Any of:
string format: date-time
/^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$/
minute
required

The API Minute Cap policy and its live state.

object
limit
required

Credits the organization may spend in one sixty-second window.

integer
>= -9007199254740991 <= 9007199254740991
used
required

Credits spent in the window that is currently open.

integer
>= -9007199254740991 <= 9007199254740991
remaining
required

Credits left in the current window.

integer
>= -9007199254740991 <= 9007199254740991
window_seconds
required

How long the window lasts. Always sixty seconds.

integer
>= -9007199254740991 <= 9007199254740991
resets_at
required
Any of:
string format: date-time
/^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$/
costs
required

What each kind of call costs in credits.

object
request
required

What one ordinary call costs.

integer
>= -9007199254740991 <= 9007199254740991
ai_generation
required

What generating a form from a prompt costs.

integer
>= -9007199254740991 <= 9007199254740991
degraded
required

True when the numbers came from a per-process fallback because the shared counter was unreachable. Treat them as approximate.

boolean

Example 

{
  "plan": "free",
  "api": {
    "plan": "free"
  }
}

401

Section titled “401”

Default Response

Media typeapplication/json
object
code
required

The stable code to branch on.

string
Allowed values: INVALID_INPUT UNAUTHORIZED PERSONAL_ACCESS_TOKEN_EXPIRED PERSONAL_ACCESS_TOKEN_REVOKED PLAN_LIMIT_REACHED PRO_FEATURE_REQUIRED FORBIDDEN FORM_PUBLISH_EMAIL_UNVERIFIED ORGANIZATION_MEMBER_BLOCKED PERSONAL_ACCESS_TOKEN_NOT_PERMITTED NOT_FOUND FORM_NOT_PUBLISHED NO_DRAFT_DURING_PUBLISH FORM_ARCHIVED FORM_CONVERSION_BLOCKED FORM_PUBLISH_REVISION_CONFLICT PAYLOAD_TOO_LARGE FORM_PUBLISH_VALIDATION_FAILED FORM_SAFETY_REJECTED TOO_MANY_REQUESTS API_COOLDOWN SERVER AI_SERVICE_UNAVAILABLE SERVICE_UNAVAILABLE
message
required

A human-readable explanation. Not part of the contract; never branch on it.

string
request_id
required

The ID of the failed request, also sent as the X-Request-Id response header.

string

Example 

{
  "code": "INVALID_INPUT"
}

403

Section titled “403”

Default Response

Media typeapplication/json
object
code
required

The stable code to branch on.

string
Allowed values: INVALID_INPUT UNAUTHORIZED PERSONAL_ACCESS_TOKEN_EXPIRED PERSONAL_ACCESS_TOKEN_REVOKED PLAN_LIMIT_REACHED PRO_FEATURE_REQUIRED FORBIDDEN FORM_PUBLISH_EMAIL_UNVERIFIED ORGANIZATION_MEMBER_BLOCKED PERSONAL_ACCESS_TOKEN_NOT_PERMITTED NOT_FOUND FORM_NOT_PUBLISHED NO_DRAFT_DURING_PUBLISH FORM_ARCHIVED FORM_CONVERSION_BLOCKED FORM_PUBLISH_REVISION_CONFLICT PAYLOAD_TOO_LARGE FORM_PUBLISH_VALIDATION_FAILED FORM_SAFETY_REJECTED TOO_MANY_REQUESTS API_COOLDOWN SERVER AI_SERVICE_UNAVAILABLE SERVICE_UNAVAILABLE
message
required

A human-readable explanation. Not part of the contract; never branch on it.

string
request_id
required

The ID of the failed request, also sent as the X-Request-Id response header.

string
required_permission
required
Any of:
string

Example 

{
  "code": "INVALID_INPUT"
}

429

Section titled “429”

A rejected call. The organization budget names the policy it rejected the call under; the request floor that bounds hammering sends the envelope alone.

Media typeapplication/json
Any of:
object
code
required

The stable code to branch on.

string
Allowed values: INVALID_INPUT UNAUTHORIZED PERSONAL_ACCESS_TOKEN_EXPIRED PERSONAL_ACCESS_TOKEN_REVOKED PLAN_LIMIT_REACHED PRO_FEATURE_REQUIRED FORBIDDEN FORM_PUBLISH_EMAIL_UNVERIFIED ORGANIZATION_MEMBER_BLOCKED PERSONAL_ACCESS_TOKEN_NOT_PERMITTED NOT_FOUND FORM_NOT_PUBLISHED NO_DRAFT_DURING_PUBLISH FORM_ARCHIVED FORM_CONVERSION_BLOCKED FORM_PUBLISH_REVISION_CONFLICT PAYLOAD_TOO_LARGE FORM_PUBLISH_VALIDATION_FAILED FORM_SAFETY_REJECTED TOO_MANY_REQUESTS API_COOLDOWN SERVER AI_SERVICE_UNAVAILABLE SERVICE_UNAVAILABLE
message
required

A human-readable explanation. Not part of the contract; never branch on it.

string
request_id
required

The ID of the failed request, also sent as the X-Request-Id response header.

string
policy
required

The policy that rejected the call.

string
Allowed values: minute burst
plan
required

The plan whose numbers were applied.

string
Allowed values: free pro
limit
required

The policy limit in credits.

integer
>= -9007199254740991 <= 9007199254740991
used
required

Credits already spent in the open window.

integer
>= -9007199254740991 <= 9007199254740991
remaining
required

Credits still available under the policy.

integer
>= -9007199254740991 <= 9007199254740991
cost
required

What the rejected call would have cost.

integer
>= -9007199254740991 <= 9007199254740991
window_seconds
required

How long the policy window lasts.

integer
>= -9007199254740991 <= 9007199254740991
cooldown_until
required
Any of:
string format: date-time
/^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$/
resets_at
required

When the window that rejected the call ends.

string format: date-time
/^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$/
retry_after_seconds
required

Seconds to wait before retrying. Also sent as the Retry-After response header.

integer
>= -9007199254740991 <= 9007199254740991
upgrade_url
required
Any of:
string

Example 

{
  "code": "INVALID_INPUT",
  "policy": "minute",
  "plan": "free"
}

500

Section titled “500”

Default Response

Media typeapplication/json
object
code
required

The stable code to branch on.

string
Allowed values: INVALID_INPUT UNAUTHORIZED PERSONAL_ACCESS_TOKEN_EXPIRED PERSONAL_ACCESS_TOKEN_REVOKED PLAN_LIMIT_REACHED PRO_FEATURE_REQUIRED FORBIDDEN FORM_PUBLISH_EMAIL_UNVERIFIED ORGANIZATION_MEMBER_BLOCKED PERSONAL_ACCESS_TOKEN_NOT_PERMITTED NOT_FOUND FORM_NOT_PUBLISHED NO_DRAFT_DURING_PUBLISH FORM_ARCHIVED FORM_CONVERSION_BLOCKED FORM_PUBLISH_REVISION_CONFLICT PAYLOAD_TOO_LARGE FORM_PUBLISH_VALIDATION_FAILED FORM_SAFETY_REJECTED TOO_MANY_REQUESTS API_COOLDOWN SERVER AI_SERVICE_UNAVAILABLE SERVICE_UNAVAILABLE
message
required

A human-readable explanation. Not part of the contract; never branch on it.

string
request_id
required

The ID of the failed request, also sent as the X-Request-Id response header.

string

Example 

{
  "code": "INVALID_INPUT"
}

Your next form could be the best-looking thing on your site.

Free forever. Unlimited responses. No signup to start.

Start building — free
4.9