Shared user usage limits

A Global Organization Limit is one monthly credit cap per person across an enterprise root and all its sub-organizations. Switching organizations does not give that person another shared allowance. This is not a pooled budget shared by every member of the enterprise.

The shared cap is separate from the existing organization default, group, and individual limits. Usage must pass both the shared cap and the applicable limit in the current organization. Setting or removing a shared cap does not change those per-organization limits.

For example, a person with a 5M shared cap who uses 3M credits in one organization and 2M in another reaches the same 5M cap. You cannot configure it to count only selected sub-organizations.

Before you start

Authenticate with a human Owner API key or JWT acting in the enterprise root organization. Owners acting in a sub-organization, Managers, other members, and service-account credentials cannot administer shared caps.

Shared usage limits must be enabled for your Factory-hosted enterprise. The root and its active sub-organizations must use the same region. These endpoints are not supported on customer-hosted deployments.

Use the person's human user ID as principalId, not an email address, directory group ID, or service-account ID. The examples below use placeholder IDs; replace them with your users' IDs.

Read configured caps

GET /api/v0/organization/usage/limits/shared lists the configured shared caps for the authenticated root.

curl https://api.factory.ai/api/v0/organization/usage/limits/shared \
  -H "Authorization: Bearer $FACTORY_API_KEY"

Example response:

{
  "principals": [
    { "principalId": "user_123", "limit": 5000000 },
    { "principalId": "user_456", "limit": 0 }
  ]
}

An empty principals array means no shared caps are configured. This endpoint returns configuration, not current usage or remaining credits.

Set or remove caps

PUT /api/v0/organization/usage/limits/shared sets or removes up to 100 unique human user IDs per request. It updates only the submitted users; it does not replace the entire shared-cap list.

Amounts are credits, not millions of credits. 5000000 means 5M credits. 0 blocks usage; it is not the same as removing the cap. There is no 1M minimum for shared caps. Integer amounts cannot exceed 9007199254740991.

This request sets a 5M cap for one user, blocks a second, and removes a third user's shared cap:

curl -X PUT https://api.factory.ai/api/v0/organization/usage/limits/shared \
  -H "Authorization: Bearer $FACTORY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "principals": [
      { "principalId": "user_123", "limit": 5000000 },
      { "principalId": "user_456", "limit": 0 },
      { "principalId": "user_789", "limit": null }
    ]
  }'

Example response:

{
  "updated": [
    { "principalId": "user_123", "limit": 5000000 },
    { "principalId": "user_456", "limit": 0 },
    { "principalId": "user_789", "limit": null }
  ],
  "errors": []
}

Removing the shared cap does not remove any organization default, group, or individual limits.

Check every entry's result

A successful HTTP response can still contain per-entry errors. Service-account and reserved IDs are reported in errors, while valid human entries save together:

{
  "updated": [
    { "principalId": "user_123", "limit": 5000000 }
  ],
  "errors": [
    {
      "principalId": "sa_build",
      "error": "Shared usage limits apply only to people."
    }
  ]
}

An empty batch, more than 100 entries, duplicate IDs, malformed ID or amount shapes, negative amounts, fractional amounts, or amounts above the supported integer range reject the request rather than partially applying it.

Handle errors and uncertain writes

These operations do not automatically retry writes. A failed read does not mean the cap list is empty, and responses are not cacheable.

Audit changes

Each actual shared-cap change records a user_limit_change event in the root organization's audit log. API changes use source public_api_v0 and identify the authenticated actor, target user, and previous and new cap values. The audit event is recorded in the same transaction as the cap change.

The payload distinguishes a shared cap with aggregationScope: "root". Its fromTokens and toTokens fields hold the previous and new credit amounts; null represents an absent cap.

See the Organization Management API for the generated request and response schemas.