Workspaces
System Limitations
Understand workspace limits, organization hierarchy constraints, billing account restrictions, and performance considerations to design scalable implementations.
Understanding the system’s operational limits is crucial for designing a scalable implementation and planning for future growth. These limits are in place to ensure optimal performance, reliability, and a consistent experience across all workspaces.
Workspace Limits
Workspaces are the top-level containers and are designed to handle enterprise-scale operations.| Resource | Limit | Details and Considerations |
|---|---|---|
| Organizations | 1,000 per Workspace | This is the total number of organizations that can exist within a single workspace, including all levels of the hierarchy. |
| Members | 100 per Workspace | A workspace can have up to 100 users with assigned roles (Owner, Admin, Viewer). |
| Billing Mode | Set once, permanent | The billing mode (Single, Assigned, or Pooled) is chosen during workspace creation and cannot be changed. Choose carefully based on your long-term business structure. |
Organization Hierarchy Limits
The hierarchical structure is designed for flexibility but has limits to ensure efficient data traversal and management.| Aspect | Limit | Details |
|---|---|---|
| Hierarchy Depth | 10 levels | The maximum allowed nesting depth of parent-child organizations. |
| Direct Children | 100 per Organization | An individual organization cannot have more than 100 direct children. |
| Total Descendants | Effectively unlimited | While there is no direct limit on total descendants, the 1,000 organization per workspace limit provides a practical ceiling. |
| Organization Name | 50 characters | The display name for an organization is limited to 50 characters. |
Hierarchy Examples
The diagrams below illustrate the depth and child limits.Billing and Subscription Limits
Billing account limits are a key factor in how you structure your financial operations and can vary by billing mode.| Resource | Limit | Details |
|---|---|---|
| Billing Accounts | 1 (in Single mode) | A workspace in Single billing mode is restricted to exactly one billing account. |
| Billing Accounts | 10 (in Assigned/Pooled modes) | A workspace can have up to 10 billing accounts when using the Assigned or Pooled billing modes. |
| Subscriptions | 3 per Billing Account | A single billing account cannot have more than 3 active subscriptions. |
| Payment Methods | 5 per Billing Account | Up to 5 payment methods can be stored securely for each billing account. |
Working with Limits: The Subscription Limit
If a customer requires more than 3 separate subscriptions for invoicing purposes, you can create additional billing accounts for them. Use Case: An MSP’s client needs 5 separate invoices for 5 different departments. Solution:- Create two Billing Accounts for the client (e.g., “Client ABC - Billing 1” and “Client ABC - Billing 2”).
- Add 3 subscriptions to the first billing account and 2 to the second.
- In the client’s Organization structure, assign different departments (or groups of departments) to the appropriate billing account. This is only possible if the workspace is in
Assignedmode and these department groups are structured as top-level organizations.
Performance Considerations
The system is highly optimized, but certain operations are inherently more complex than others.| Operation | Complexity | Typical Duration & Notes |
|---|---|---|
| Create Organization | O(1) | Very fast (< 100ms). Involves a single atomic write operation. |
| Move Organization | O(n) | n is the number of descendants. Performance depends on the size of the subtree being moved. |
| Calculate Usage & Limits | O(1) (Optimized) | Fast (< 200ms). Uses batch operations to fetch all required data, avoiding slow, recursive lookups. |
| List Organizations | O(n) | Paginated for performance. A single page of up to 100 items typically loads in under 500ms. |
Best Practices for Scale
- Prefer Wider Hierarchies: Where possible, favor wider and shallower hierarchies over deeply nested ones. This simplifies management and visualization.
- Use Batch Operations: When interacting with the API, use bulk endpoints for creating or updating multiple entities whenever available to improve throughput.
- Leverage Pagination: When fetching large lists of resources, always use pagination cursors to ensure fast and reliable responses.
Error Handling
When a limit is reached, the API will return a clear error message.| Error | Typical Cause | Recommended Solution |
|---|---|---|
| Hierarchy Depth Exceeded | Attempting to create an organization at level 11 or deeper. | Restructure the hierarchy to be wider rather than deeper. Use tags or metadata for further classification if needed. |
| Max Children Exceeded | Attempting to add the 101st direct child to an organization. | Create intermediate organizational layers. For example, group children by region or function. |
| Subscription Limit Exceeded | Attempting to add a 4th active subscription to a billing account. | Create an additional billing account to house the new subscription as described above. |
| Quota or Limit Exceeded | Resource usage has reached the maximum allowed by the subscription or an organization’s limit. | Upgrade the subscription to increase capacity or reduce usage. |
Planning for Growth
Proactively monitor your workspace’s metrics to avoid unexpectedly hitting system limits.Scaling Strategies
- Workspace Segmentation: For very large or diverse enterprises, consider splitting operations across multiple workspaces. You could segment by geography (e.g., “Company AMER,” “Company EMEA”) or by business unit.
- Hierarchy Optimization: Regularly review your organization structure. Flattening the hierarchy where it makes sense can simplify management.
- Contact Support: If you project that your business will exceed these limits, please contact our support team to discuss options. Enterprise plans may offer higher or customizable limits.