CumulusDocs
Open Studio
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 use path).
  • MCP tool: sdk_client_call with operationId: "runs.capacity" (path arguments use input.path). Legacy alias: runs_capacity. Connect to your authenticated /mcp endpoint 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
curl --fail-with-body -sS "${CUMULUS_BASE_URL%/}/api/v1/runs/capacity" \
  -H "Authorization: Bearer $CUMULUS_API_KEY"

TypeScript

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
OpenAPI JSON
{
  "parameters": [],
  "requestBody": null
}

Responses

HTTP 200

Read admission capacity per channel: configured limit and runs holding it

application/json

FieldType or valuesRequiredDescription and limits
itemsarray of objectRequired—
items[].channel"cloud" · "phone" · "web"Required—
items[].activeintegerRequiredAt least 0. At most 9007199254740991.
items[].limitintegerRequiredMaximum items to return in this page. At least 0. At most 9007199254740991.
items[].admission_enabledbooleanRequired—

Error responses

HTTPDescription
4XXTyped error (ApiError)
5XXTyped error (ApiError)

Errors use the shared error envelope. Inspect error.code, retryable, outcome and details before retrying.

Complete OpenAPI schema
OpenAPI JSON
{
  "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
OpenAPI JSON
{
  "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.

Content version 36a00777Customer SDKMarkdown source
Check run capacity · Cumulus developer docs