Skip to main content
Use runs.start when a job, workflow, tool, agent, or custom workload needs a budget envelope before it starts. The customer remains the economic actor; the run is the workload label and spend reservation. 
// Reserve spend before the workload creates cost.
const { result, error } = await unprice.runs.start({
  customerId: "cus_1234567890",
  budgetAmountMinor: 5000,
  idempotencyKey: "run:req_123",
  workloadType: "workflow",
  workloadId: "wf_summary_123",
  traceId: "trace_123"
});

if (error) {
  console.error(error.message);
  return;
}

// A running run means the budget reservation was accepted.
console.log(result.runId);

{
  "runId": "brun_123",
  "status": "running",
  "customerId": "cus_1234567890",
  "budgetAmountMinor": 5000,
  "consumedAmountMinor": 0,
  "remainingAmountMinor": 5000,
  "currency": "USD",
  "workloadType": "workflow",
  "workloadId": "wf_summary_123",
  "traceId": "trace_123",
  "parentRunId": null
}

​
Request

​
customerId
string
The customer ID. Required when the API key has no default customer binding.
​
budgetAmountMinor
number
required
Budget in currency minor units. For USD, 5000 means $50.00.
​
idempotencyKey
string
required
Logical key used to deduplicate the run start request.
​
workloadType
"agent" | "workflow" | "job" | "tool" | "custom"
Optional label for the kind of workload that will spend the budget.
​
workloadId
string
Optional ID from your system for the workload.
​
traceId
string
Optional trace ID for connecting the run to your logs or traces.
​
parentRunId
string
Optional parent run ID for nested workloads.
​
metadata
object
Optional metadata stored with the run.
​
expiresAt
number
Optional epoch-millisecond expiration timestamp.

​
Response

Returns the started budget run. remainingAmountMinor is the amount still available for runs.consume.