CumulusDocs
Open Studio
On this page

Estimate a test run

Estimate trial count, cost and duration before starting a test run.

Operation ID: test_runs.estimate.

Request

POST /api/v1/test-runs/estimate

  • TypeScript SDK: client.test_runs.estimate (path arguments use path).
  • MCP tool: sdk_client_call with operationId: "test_runs.estimate" (path arguments use input.path). Legacy alias: test_runs_estimate. 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

Copy an agent version and suite IDs from publications.list and test_suites.list. Estimate the same request you intend to send to test_runs.create; the estimate is not a test result or a guarantee of final cost.

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 -X POST "${CUMULUS_BASE_URL%/}/api/v1/test-runs/estimate" \
  -H "Authorization: Bearer $CUMULUS_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "agent_id": "service-guide",
  "version": 0,
  "suite_ids": [
    "44444444-4444-4444-8444-444444444444"
  ],
  "trials": 1
}'

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.test_runs.estimate({
  "body": {
    "agent_id": "service-guide",
    "version": 0,
    "suite_ids": [
      "44444444-4444-4444-8444-444444444444"
    ],
    "trials": 1
  }
});

Input schema

Path, query and header parameters

No path or query parameters.

JSON request body

FieldType or valuesRequiredDescription and limits
agent_idstringRequiredAgent identifier in the environment selected by your API key. minLength: 1. maxLength: 256. pattern: ^[A-Za-z0-9][A-Za-z0-9_.:-]*$.
versionintegerRequiredAt least 0. At most 2147483647.
suite_idsarray of string (uuid)RequiredIdentifiers of the test suites to execute. minItems: 1. maxItems: 10.
case_idsarray of stringOptionalminItems: 1. maxItems: 100.
trialsintegerOptionalAt least 1. At most 10.
baseline_test_run_idstring (uuid)Optionalpattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$.
Complete OpenAPI schema
OpenAPI JSON
{
  "parameters": [],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/TestRunCreateRequest"
        }
      }
    }
  }
}

Responses

HTTP 200

Estimate a test run's trials, cost and duration before starting it

application/json

FieldType or valuesRequiredDescription and limits
trialsintegerRequiredAt least 0. At most 9007199254740991.
est_cost_usdnumberRequiredAt least 0.
est_minutesnumberRequiredAt least 0.

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": "Estimate a test run's trials, cost and duration before starting it",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/TestRunsEstimateResponse200"
        }
      }
    }
  },
  "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": {
      "TestRunCreateRequest": {
        "type": "object",
        "properties": {
          "agent_id": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256,
            "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]*$"
          },
          "version": {
            "type": "integer",
            "minimum": 0,
            "maximum": 2147483647
          },
          "suite_ids": {
            "minItems": 1,
            "maxItems": 10,
            "type": "array",
            "items": {
              "type": "string",
              "format": "uuid",
              "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"
            }
          },
          "case_ids": {
            "minItems": 1,
            "maxItems": 100,
            "type": "array",
            "items": {
              "type": "string",
              "minLength": 1,
              "maxLength": 64,
              "pattern": "^[a-z0-9][a-z0-9_-]*$"
            }
          },
          "trials": {
            "type": "integer",
            "minimum": 1,
            "maximum": 10
          },
          "baseline_test_run_id": {
            "type": "string",
            "format": "uuid",
            "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"
          }
        },
        "required": [
          "agent_id",
          "version",
          "suite_ids"
        ],
        "additionalProperties": false
      },
      "TestRunsEstimateResponse200": {
        "type": "object",
        "properties": {
          "trials": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991
          },
          "est_cost_usd": {
            "type": "number",
            "minimum": 0
          },
          "est_minutes": {
            "type": "number",
            "minimum": 0
          }
        },
        "required": [
          "trials",
          "est_cost_usd",
          "est_minutes"
        ],
        "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 ddea3f79Customer SDKMarkdown source
Estimate a test run · Cumulus developer docs