Only a Final Build owned by the authenticated workspace is callable. Start by listing or inspecting the build, confirm its input contract and fixed credit price, then create one intended run and save the returned run_id.
Before every live run
Confirm the selected Signaliz workspace.
List the workspace’s Final Builds or inspect the exact
BLD-...ID.Match your input to the delivered
input_schema.Review
fixed_credits_per_runandclay_credits_budget_per_run.Use one stable idempotency key for that intended run.
Save the returned UUID
run_idand recover it until terminal.
The JSON input may be up to 256 KiB. When input.records is used, a run accepts at most 5,000 record objects. Split larger work according to the delivered runbook.
REST API
Use the production base https://api.signaliz.com/functions/v1/api with a Bearer API key from the owning workspace.
List delivered builds
curl "https://api.signaliz.com/functions/v1/api/v1/managed-builds" \ -H "Authorization: Bearer YOUR_SIGNALIZ_API_KEY"
Inspect the build contract
curl "https://api.signaliz.com/functions/v1/api/v1/managed-builds/BLD-XXXXXXXXXXXX" \ -H "Authorization: Bearer YOUR_SIGNALIZ_API_KEY"
Create one intended run
Use a write-capable or spend:credits API key.
curl -X POST \ "https://api.signaliz.com/functions/v1/api/v1/managed-builds/BLD-XXXXXXXXXXXX/runs" \ -H "Authorization: Bearer YOUR_SIGNALIZ_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: managed-build-2026-08-03-run-001" \ -d '{"input":{"records":[{"domain":"example.com"}]}}'An accepted run returns HTTP 202, the durable run_id, fixed credits charged, billing status, and queue status.
Recover status and results
curl "https://api.signaliz.com/functions/v1/api/v1/managed-build-runs/RUN_UUID?limit=100" \ -H "Authorization: Bearer YOUR_SIGNALIZ_API_KEY"
limit can be 1–500. Poll the same run_id; do not submit a new paid run because a client timed out.
MCP and AI clients
Managed Builds expose four tools:
list_managed_buildsget_managed_buildrun_managed_buildget_managed_build_run
For run_managed_build, first pass dry_run: true. The tool returns the exact fixed price and Clay budget without charging or dispatching. For live execution, use confirm_spend: true and set max_credits to an approved ceiling.
{ "build_id": "BLD-XXXXXXXXXXXX", "input": { "records": [{ "domain": "example.com" }] }, "idempotency_key": "managed-build-2026-08-03-run-001", "dry_run": false, "confirm_spend": true, "max_credits": 125 }If the fixed price exceeds max_credits, MCP stops before charge. If confirm_spend is absent, it returns APPROVAL_REQUIRED instead of creating a run.
CLI
signaliz builds list signaliz builds get --build-id BLD-XXXXXXXXXXXX signaliz builds run --build-id BLD-XXXXXXXXXXXX --input request.json --idempotency-key managed-build-2026-08-03-run-001 signaliz builds status --run-id RUN_UUID --limit 100
The run command creates live spend. Inspect the build first and use the same idempotency key only to recover that exact intended run.
TypeScript SDK
import { Signaliz } from "@signaliz/sdk"; const signaliz = new Signaliz({ apiKey: process.env.SIGNALIZ_API_KEY! }); const { build } = await signaliz.getManagedBuild("BLD-XXXXXXXXXXXX"); const started = await signaliz.runManagedBuild( build.build_id, { records: [{ domain: "example.com" }] }, "managed-build-2026-08-03-run-001", ); const finished = await signaliz.getManagedBuildRun(started.run.run_id, 100);Idempotency and billing
Each new intended execution needs a new idempotency key. Reusing the same key with the same build and input replays the original reservation rather than charging twice. Reusing it with a different build or different input returns an idempotency conflict.
Credits are reserved atomically before dispatch. If the workspace has insufficient credits, no run is dispatched. If dispatch fails after reservation, the reservation is refunded and the response reports zero credits charged with refunded billing state.
Next: Troubleshoot a managed build and read its receipts.