Runs
Lifecycle
-
Estimate.
POST /projects/{projectId}/workflows/{workflowId}/estimatereturns what a run would cost (scoperuns.read). -
Start.
POST /projects/{projectId}/workflows/{workflowId}/runsstarts a run (scoperuns.execute). The body is the same as the dashboard's run request. SendacceptEstimateCreditsto confirm the cost you saw in the estimate.Allowing media to be sent. Some apps have a step that sends your media to an AI service; their workflow lists an input with the id
allowMediaEgress. To allow it for the run you start, send"brief": { "inputs": { "allowMediaEgress": true } }. The key needs themedia.egressscope for that; without it the start answers403insufficient_scopewithrequiredScopes: ["media.egress"]and nothing starts. The value is never assumed: a run that needs the permission and does not send it answers400APP_INPUT_MISSINGwithinputId: "allowMediaEgress". It applies to that run only, and the201answer then carriesmediaEgress: { "allowed": true, "steps": [{ "stepName", "sends" }] }so your own log shows what was allowed to leave. -
Status.
GET /projects/{projectId}/runs/{runId}returns the status (queued,running,succeeded,failedorcancelled), the steps, the credits and a failure code if the run failed.GET /projects/{projectId}/runslists runs and filters byworkflowIdandstatus. -
Stop, resume, retry.
POST .../runs/{runId}/stop,/resumeand/retry(scoperuns.execute). A key can retry or resume only runs it started. Resume and retry start paid work again: they charge the key that calls them, count against the hourly run limit, and are never queued. When the limit is full they answer429RUN_RATE_LIMITEDwithRetry-After,error.retryAfterSecondsanderror.resetsAt. Try again after that time.
Results are paged with ?limit= and ?cursor=; the answer holds data and nextCursor.
A start under the hourly limit answers 201 with the run. The API never turns on sending your source
media to outside services; a run started through the API keeps that off.
The hourly run limit
Each key has a limit on how many runs it can start per hour. A start over the limit is not refused. It is queued.
Queued starts
A queued start answers 202:
{
"id": "<run request id>",
"status": "queued",
"estimatedStartAt": "2026-11-02T15:30:00Z",
"workflowId": "...",
"projectId": "..."
}
The id is a run request id, not a run id. ReelBolt starts the request when the hourly limit allows, in
the order you sent them. A key can have 20 waiting requests (queued or starting); one more answers 429 run_queue_full with Retry-After and the limit.
GET /projects/{projectId}/run-requestsandGET .../run-requests/{id}show the request: its status (queued,starting,started,cancelledorrefused),estimatedStartAt(while queued), therunIdonce started anderrorwith acodeandmessageif it was refused.POST .../run-requests/{id}/cancelcancels a request, only while it isqueued; otherwise it answers409run_request_not_cancellable.
ReelBolt runs the credit and cap checks again when the request actually starts. A request can therefore end
as refused, with the same code and message a direct start would have given, for example
API_KEY_BUDGET_EXCEEDED or INSUFFICIENT_CREDITS. You can also get the run_request.started and
run_request.refused webhook events.
Outputs and download links
GET /projects/{projectId}/runs/{runId}/outputslists the outputs of a run (scopeoutputs.read).POST /projects/{projectId}/outputs/{stepResultId}/linkreturns{ "url": "...", "expiresAt": "..." }. The link works for 15 minutes. Ask for a new one when it expires.
Content checks run before an output can be shared. While a check is still running, the link request answers
202 with CONTENT_MODERATION_PENDING and a Retry-After header. Try again after that many seconds. A
blocked output answers 422 CONTENT_BLOCKED; other check results answer 409.