On this page
Check run capacity
Read each channel’s admission status, concurrent-run limit and active count.
Operation ID: runs.capacity.
Request
GET /api/v1/runs/capacity
- TypeScript SDK:
client.runs.capacity(path arguments usepath). - MCP tool:
sdk_client_callwithoperationId: "runs.capacity"(path arguments useinput.path). Legacy alias:runs_capacity. Connect to your authenticated/mcpendpoint with an API key for the same environment. - Minimum API key role: viewer.
- Idempotency: No idempotency header required.
Read resource IDs from earlier responses and use a key for the same environment.
Request example
Set each path variable to an ID returned by an earlier API request.
Set CUMULUS_BASE_URL to your workspace API URL and CUMULUS_API_KEY to a key for that environment. Example values are synthetic.
cURL
curl --fail-with-body -sS "${CUMULUS_BASE_URL%/}/api/v1/runs/capacity" \
-H "Authorization: Bearer $CUMULUS_API_KEY"
TypeScript
import { Cumulus } from "@cumulus/sdk";
const baseUrl = process.env.CUMULUS_BASE_URL;
const apiKey = process.env.CUMULUS_API_KEY;
if (!baseUrl || !apiKey) throw new Error("Set CUMULUS_BASE_URL and CUMULUS_API_KEY");
const client = new Cumulus({ baseUrl, apiKey });
const response = await client.runs.capacity({});
Integration notes
If admission_enabled is false or the phone channel is absent, ask Cumulus to configure capacity and open admission for this environment.
Input schema
Path, query and header parameters
No path or query parameters.
JSON request body
This operation has no JSON request body.
Complete OpenAPI schema
{
"parameters": [],
"requestBody": null
}
Responses
HTTP 200
Read admission capacity per channel: configured limit and runs holding it
application/json
| Field | Type or values | Required | Description and limits |
|---|---|---|---|
items | array of object | Required | — |
items[].channel | "cloud" · "phone" · "web" | Required | — |
items[].active | integer | Required | At least 0. At most 9007199254740991. |
items[].limit | integer | Required | Maximum items to return in this page. At least 0. At most 9007199254740991. |
items[].admission_enabled | boolean | Required | — |
Error responses
| HTTP | Description |
|---|---|
| 4XX | Typed error (ApiError) |
| 5XX | Typed error (ApiError) |
Errors use the shared error envelope. Inspect error.code, retryable, outcome and details before retrying.
Complete OpenAPI schema
{
"200": {
"description": "Read admission capacity per channel: configured limit and runs holding it",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RunsCapacityResponse200"
}
}
}
},
"4XX": {
"description": "Typed error (ApiError)",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
},
"5XX": {
"description": "Typed error (ApiError)",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
}
}
Referenced schemas
Expand the complete OpenAPI definitions for integrations that generate their own clients.
Complete OpenAPI schema
{
"components": {
"schemas": {
"RunsCapacityResponse200": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"channel": {
"type": "string",
"enum": [
"cloud",
"phone",
"web"
]
},
"active": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"limit": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"admission_enabled": {
"type": "boolean"
}
},
"required": [
"channel",
"active",
"limit",
"admission_enabled"
],
"additionalProperties": false
}
}
},
"required": [
"items"
],
"additionalProperties": false
},
"ApiError": {
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "string",
"enum": [
"unauthenticated",
"forbidden",
"not_found",
"conflict",
"invalid_request",
"idempotency_conflict",
"policy_denied",
"capability_unavailable",
"provider_unavailable",
"knowledge_unavailable",
"publication_invalid",
"run_not_active",
"rate_limited",
"outcome_unknown",
"internal"
]
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"outcome": {
"type": "string",
"enum": [
"none",
"unknown"
]
},
"details": {
"type": "object",
"additionalProperties": {}
}
},
"required": [
"code",
"message",
"retryable",
"outcome"
],
"additionalProperties": false
}
},
"required": [
"error"
],
"additionalProperties": false
}
}
}
}
Errors and recovery
See API error handling and Troubleshooting.