Capacity (Seats)
List Allocations
List users allocated to a tenant’s active subscription, with capacity summary and pagination.
GET
/
api
/
public
/
capacity
/
allocations
curl "https://app.crovver.com/api/public/capacity/allocations?requestingEntityId=workspace_123&status=active&page=1&limit=50" \
-H "Authorization: Bearer sk_live_..."
const result = await crovver.capacity.getAllocations({
requestingEntityId: "workspace_123",
});
result.allocations.forEach((user) => {
console.log(`${user.externalUserId} — ${user.email} (${user.status})`);
});
const { activeCount, capacityUnits, utilizationPercentage, exceeded } = result.capacity;
console.log(`${activeCount} / ${capacityUnits} seats (${utilizationPercentage}%)`);
// Page through all users including removed
const page2 = await crovver.capacity.getAllocations({
requestingEntityId: "workspace_123",
status: "all",
page: 2,
limit: 25,
});
// Active users, first page (default)
$result = $client->getAllocations('workspace_123');
foreach ($result->allocations as $user) {
echo $user->externalUserId . ' — ' . $user->email;
echo ' (' . $user->status . ')';
}
echo $result->capacity->activeCount . ' / ' . $result->capacity->capacityUnits . ' seats';
echo $result->capacity->utilizationPercentage . '% utilized';
if ($result->capacity->exceeded) {
// Over limit — prompt upgrade
}
// Page 2, all statuses
$page2 = $client->getAllocations(
requestingEntityId: 'workspace_123',
status: 'all',
page: 2,
limit: 25,
);
echo $page2->pagination->total . ' total users';
{
"success": true,
"data": {
"allocations": [
{
"externalUserId": "user_1",
"email": "alice@acme.com",
"name": "Alice",
"status": "active",
"allocatedAt": "2026-05-01T10:00:00.000Z",
"removedAt": null,
"metadata": { "addedBy": "admin_789" }
},
{
"externalUserId": "user_2",
"email": "bob@acme.com",
"name": "Bob",
"status": "active",
"allocatedAt": "2026-05-03T14:30:00.000Z",
"removedAt": null,
"metadata": {}
}
],
"capacity": {
"activeCount": 8,
"capacityUnits": 10,
"utilizationPercentage": 80,
"exceeded": false
},
"pagination": {
"total": 8,
"page": 1,
"limit": 50,
"totalPages": 1,
"hasNextPage": false,
"hasPreviousPage": false
}
}
}
{
"success": false,
"error": "Missing required query param: requestingEntityId"
}
{
"success": false,
"error": "No active subscription found for this tenant"
}
Returns the seat allocations for a tenant’s active subscription. Filter by status, paginate through results, and inspect real-time capacity utilization.
Query Parameters
string
required
The external tenant ID from your application.
string
default:"active"
Filter allocations by status. One of:
active— currently allocated users (default)removed— deallocated usersall— both active and removed
number
default:"1"
1-based page number.
number
default:"50"
Number of results per page. Maximum 100.
Authentication
Requires a secret key (Authorization: Bearer sk_live_...) or service key (x-service-key).
Response
| Field | Type | Description |
|---|---|---|
allocations | AllocationUser[] | Paginated list of allocated users |
allocations[].externalUserId | string | Your app’s user ID |
allocations[].email | string | null | User’s email |
allocations[].name | string | null | User’s display name |
allocations[].status | "active" | "removed" | Current allocation status |
allocations[].allocatedAt | string | ISO 8601 timestamp of when the seat was assigned |
allocations[].removedAt | string | null | ISO 8601 timestamp of deallocation (if removed) |
allocations[].metadata | object | Metadata stored at allocation time |
capacity.activeCount | number | Current active seat count |
capacity.capacityUnits | number | Total seat limit on the subscription |
capacity.utilizationPercentage | number | activeCount / capacityUnits × 100 |
capacity.exceeded | boolean | Whether active seats exceed the limit |
pagination.total | number | Total matching records |
pagination.page | number | Current page |
pagination.totalPages | number | Total pages |
pagination.hasNextPage | boolean | Whether a next page exists |
pagination.hasPreviousPage | boolean | Whether a previous page exists |
curl "https://app.crovver.com/api/public/capacity/allocations?requestingEntityId=workspace_123&status=active&page=1&limit=50" \
-H "Authorization: Bearer sk_live_..."
const result = await crovver.capacity.getAllocations({
requestingEntityId: "workspace_123",
});
result.allocations.forEach((user) => {
console.log(`${user.externalUserId} — ${user.email} (${user.status})`);
});
const { activeCount, capacityUnits, utilizationPercentage, exceeded } = result.capacity;
console.log(`${activeCount} / ${capacityUnits} seats (${utilizationPercentage}%)`);
// Page through all users including removed
const page2 = await crovver.capacity.getAllocations({
requestingEntityId: "workspace_123",
status: "all",
page: 2,
limit: 25,
});
// Active users, first page (default)
$result = $client->getAllocations('workspace_123');
foreach ($result->allocations as $user) {
echo $user->externalUserId . ' — ' . $user->email;
echo ' (' . $user->status . ')';
}
echo $result->capacity->activeCount . ' / ' . $result->capacity->capacityUnits . ' seats';
echo $result->capacity->utilizationPercentage . '% utilized';
if ($result->capacity->exceeded) {
// Over limit — prompt upgrade
}
// Page 2, all statuses
$page2 = $client->getAllocations(
requestingEntityId: 'workspace_123',
status: 'all',
page: 2,
limit: 25,
);
echo $page2->pagination->total . ' total users';
{
"success": true,
"data": {
"allocations": [
{
"externalUserId": "user_1",
"email": "alice@acme.com",
"name": "Alice",
"status": "active",
"allocatedAt": "2026-05-01T10:00:00.000Z",
"removedAt": null,
"metadata": { "addedBy": "admin_789" }
},
{
"externalUserId": "user_2",
"email": "bob@acme.com",
"name": "Bob",
"status": "active",
"allocatedAt": "2026-05-03T14:30:00.000Z",
"removedAt": null,
"metadata": {}
}
],
"capacity": {
"activeCount": 8,
"capacityUnits": 10,
"utilizationPercentage": 80,
"exceeded": false
},
"pagination": {
"total": 8,
"page": 1,
"limit": 50,
"totalPages": 1,
"hasNextPage": false,
"hasPreviousPage": false
}
}
}
{
"success": false,
"error": "Missing required query param: requestingEntityId"
}
{
"success": false,
"error": "No active subscription found for this tenant"
}
⌘I
curl "https://app.crovver.com/api/public/capacity/allocations?requestingEntityId=workspace_123&status=active&page=1&limit=50" \
-H "Authorization: Bearer sk_live_..."
const result = await crovver.capacity.getAllocations({
requestingEntityId: "workspace_123",
});
result.allocations.forEach((user) => {
console.log(`${user.externalUserId} — ${user.email} (${user.status})`);
});
const { activeCount, capacityUnits, utilizationPercentage, exceeded } = result.capacity;
console.log(`${activeCount} / ${capacityUnits} seats (${utilizationPercentage}%)`);
// Page through all users including removed
const page2 = await crovver.capacity.getAllocations({
requestingEntityId: "workspace_123",
status: "all",
page: 2,
limit: 25,
});
// Active users, first page (default)
$result = $client->getAllocations('workspace_123');
foreach ($result->allocations as $user) {
echo $user->externalUserId . ' — ' . $user->email;
echo ' (' . $user->status . ')';
}
echo $result->capacity->activeCount . ' / ' . $result->capacity->capacityUnits . ' seats';
echo $result->capacity->utilizationPercentage . '% utilized';
if ($result->capacity->exceeded) {
// Over limit — prompt upgrade
}
// Page 2, all statuses
$page2 = $client->getAllocations(
requestingEntityId: 'workspace_123',
status: 'all',
page: 2,
limit: 25,
);
echo $page2->pagination->total . ' total users';
{
"success": true,
"data": {
"allocations": [
{
"externalUserId": "user_1",
"email": "alice@acme.com",
"name": "Alice",
"status": "active",
"allocatedAt": "2026-05-01T10:00:00.000Z",
"removedAt": null,
"metadata": { "addedBy": "admin_789" }
},
{
"externalUserId": "user_2",
"email": "bob@acme.com",
"name": "Bob",
"status": "active",
"allocatedAt": "2026-05-03T14:30:00.000Z",
"removedAt": null,
"metadata": {}
}
],
"capacity": {
"activeCount": 8,
"capacityUnits": 10,
"utilizationPercentage": 80,
"exceeded": false
},
"pagination": {
"total": 8,
"page": 1,
"limit": 50,
"totalPages": 1,
"hasNextPage": false,
"hasPreviousPage": false
}
}
}
{
"success": false,
"error": "Missing required query param: requestingEntityId"
}
{
"success": false,
"error": "No active subscription found for this tenant"
}