API Runs
Billing for workflow runs triggered through the REST API, including spend caps.
Developers running workflows through the API.
Overview#
API-triggered runs use the same billing as runs started from the product UI. Funding is wallet-based, with bundle draw first if the API caller has an eligible bundle for that workflow version.
API keys can set an optional spend cap. When a run would exceed the cap, no run record is created and the endpoint returns a synchronous spend_cap_reached error.
Authentication and spend caps#
Requests require a valid API key with run scope. If your key has a spend cap, Edgaze sums recent reserved and spent amounts before starting a run. If the quoted run would exceed the cap, no run starts.
The public endpoint has no separate account-level spend cap. Keys without an API-key cap are limited by wallet balance, bundle availability, input limits, and rate limits.
Funding and execution#
Funding order matches the UI: eligible locked bundle first, then wallet. Insufficient wallet after bundle exhaustion blocks the run.
The API enforces the same input envelope limits as the product UI. Oversized input is rejected before any charge.
On success, billing is identical to UI runs: wallet charge or bundle consumption, plus creator earnings at 80% of margin. Ordinary failed and cancelled runs are not charged. If a run is separately labeled as stopped at the compute limit, creator margin is released but already-consumed compute may be retained.
Response behavior#
POST /runs accepts a valid request before wallet or bundle funding is finalized. An insufficient wallet therefore creates a run that later becomes failed; it does not return a synchronous payment error. An API-key spend-cap failure is checked earlier and returns an error without a run record.
See the canonical funding and acceptance table for every response, record, charge, earnings, and retry outcome.
Special cases#
- Bundle via API: Works the same as the product UI when the bundle matches the workflow version.
- BYOK via API: Same orchestration and margin pricing as UI BYOK runs.
- Composed workflow: Root charge covers the summed child prices. Child creators earn independently on success.
What you see in Edgaze#
- API Vault: key creation with optional spend cap and window
- API responses: clear messages when funds or spend cap block a run
- Wallet history: the same charge lines as UI runs for the same account
Related policies#
- API Reference: REST endpoints, authentication, playground, and webhooks
- Funding Runs
- Run a Workflow
- API Vault: BYOK provider keys (not REST API keys)
- When Runs Fail
Was this useful?
Your response helps us improve the documentation.
Related documentation
How workflow runs are priced, funded, settled, and refunded. Step-by-step guides for buyers, creators, and developers.
How to open a workflow, fund a run, and what happens when it completes.
How the per-run price is built, what the creator earns, and what Edgaze keeps.