User Limits & Usage

Overview

Two related features let you meter your end-users so you can build your own free and paid tiers:

1. Per-user action limit. Set monthly_action_limit on an end-user to cap how many actions that user may run per billing cycle. You manage it yourself, one user at a time. There is no account-wide cap and no built-in tier model, so you express your tiers by setting each user's limit.
2. Usage API. Read how many actions have run in the current cycle (or an explicit date range), for the whole account or a single user.

An action is one unit of work a workflow performs, like an API call or a code step. A single workflow run produces one or more actions. Both the limit and the usage figure count actions, not runs.

Setting a user's monthly action limit

monthly_action_limit is an integer, or null. null or omitted means unlimited (no cap). Set it two ways. Either path works, and each applies the field only when you include it, so they don't overwrite each other.

REST API, with PUT /api/v1/users/{key}:

1
{ "monthly_action_limit": 5000 }

Discover JWT, by including a monthly_action_limit claim:

1
2
3
4
5
6
7
{
  "sub": "user_key_123",
  "name": "Alice",
  "email": "alice@example.com",
  "monthly_action_limit": 5000,
  "discover": true
}

The value is returned on the user object from GET /api/v1/users/{key} as monthly_action_limit (integer or null), so you can read back the current cap.

How the limit is enforced

• The cap is checked when a new workflow run is about to start for that user. If the user has already run at or above their monthly_action_limit for the current billing cycle, the new run is refused.
• Runs already in progress finish. The limit never interrupts a run that has already started, so a user can end a cycle slightly above their limit. Treat the cap as a soft ceiling, not an exact cutoff. (A run can still stop early for unrelated reasons, like an action error, a callback that times out, or an explicit cancellation.)
• A null limit skips the check entirely (unlimited).

Reading usage

1
GET /api/v1/account/usage

All query parameters are optional:

For a custom window, pass both start_time and end_time. If either is missing, the response covers the current billing cycle.

Response keys:

For one user's current-cycle usage, GET /api/v1/account/usage?user_key=user_key_123:

1
2
3
4
5
6
7
8
{
  "usage": 1523,
  "executions_count": 847,
  "active_workflows_count": 42,
  "users_count": 150,
  "start_time": "2026-11-15T00:00:00Z",
  "end_time": "2026-12-14T23:59:59Z"
}

Usage is whole-account or single-user (by user_key). There is no ranked or all-users breakdown endpoint.

Two details to keep in mind:

• When you pass user_key, the usage, executions_count, and active_workflows_count figures are scoped to that user, but users_count is always account-wide.
• On the default (current-cycle) response, start_time and end_time come back as ISO 8601. If you pass them explicitly, the response echoes the exact strings you sent rather than normalizing them.

Billing cycle

The billing cycle is anchored to the account's creation day of the month, not the calendar month. Both the per-user limit and the default usage window use this cycle, so the numbers line up.

• An account created on the 15th runs each cycle from the 15th through the 14th of the next month.
• Short months are clamped. An account created on the 31st uses the last day of a shorter month, so a February cycle starts on Feb 28.
• A cycle starts at 00:00:00 and ends one second before the next cycle begins.

Common mistakes

These are the real support issues. Run through them before you rely on limits.

Next steps

• Retrieve Account Usage: the usage endpoint reference
• Account API: the full account endpoints
• Groups & Visibility: gate which items each end-user can see