API reference · In your appWorkflows
Workflows
The workflows a project's app defines, and their runs: start, read, cancel and retry.
Workflows are defined in your app's code with @useorbits/workflows; these routes list them and their runs, start a run, and cancel or retry one. See Workflows.
The workflow run object
Fields
idstringrequiredworkflowstringrequiredstatestringrequiredOne of
running,succeeded,failed,canceled.triggerstringrequiredOne of
schedule,event,manual.trigger_textstringrequiredstarted_byFlagPerson or nullrequiredWho pressed Run now; null for a schedule or an event.
Show 4 child fieldsHide child fields
idstringrequirednamestringrequiredemailstringrequiredavatar_urlstring or nullrequired
started_atstringrequiredfinished_atstring or nullrequiredsecondsintegerrequiredFrom start to finish, or so far.
deploymentobjectrequiredShow 2 child fieldsHide child fields
idstringrequiredshastring or nullrequired
inputobjectrequiredThe JSON it started with.
outputobjectrequiredWhat the workflow returned.
errorarray of stringrequiredattemptsstringrequirednext_atstring or nullrequiredWhen the app is called for it next.
stepsarray of WorkflowSteprequiredShow 11 child fieldsHide child fields
namestringrequiredkindstringrequiredOne of
step,sleep,wait.statestringrequiredOne of
running,succeeded,failed,waiting,skipped,canceled.secondsinteger or nullrequiredTime spent running over every attempt; null for one not reached.
detailstringrequirederrorarray of stringrequiredThe last attempt's error: message, then where.
attemptsintegerrequiredretried_byFlagPerson or nullrequiredShow 4 child fieldsHide child fields
idstringrequirednamestringrequiredemailstringrequiredavatar_urlstring or nullrequired
wake_atstring or nullrequiredA sleep's end, or a wait's timeout.
eventstring or nullrequiredWhat a wait waits for.
outputobjectrequiredThe step's result; a wait's is the event's data.
A project's workflows and recent runs
The Workflows page. workflows are what the production deployment's @useorbits/workflows lists, read once it went live: each with its trigger as the page says it ("Every 15 minutes", "When order.paid happens"), its last run, and the share of its finished runs in the last 7 days that succeeded (null without any). runs are the 50 newest, each with its steps.
A run's steps are the step(), sleep() and waitFor() calls it reached, in order. A step running with an error failed an attempt and is waiting for its retry (next_at). Steps the workflow took on its last successful run that this run hasn't reached are listed after them: waiting while it runs, skipped once it failed or was canceled.
Permissions: Any team member. A non-member gets 404.
Headers
AuthorizationstringrequiredBearerand your API token:Bearer orb_live_….
Path parameters
teamstringrequiredTeam slug or
team_id.projectstringrequiredProject slug or
prj_id.
Response 200
The workflows and runs.workflowsarray of objectrequiredShow 8 child fieldsHide child fields
namestringrequireddescriptionstringrequiredschedulestring or nullrequiredFive-field cron, in UTC.
eventstring or nullrequiredretriesintegerrequiredAttempts after the first, for each step.
trigger_textstringrequiredlast_runnull or objectrequiredShow 3 child fieldsHide child fields
idstringrequiredstatestringrequiredOne of
running,succeeded,failed,canceled.atstringrequired
success_ratenumber or nullrequiredFrom 0 to 1.
runsarray of WorkflowRunrequiredShow 16 child fieldsHide child fields
idstringrequiredworkflowstringrequiredstatestringrequiredOne of
running,succeeded,failed,canceled.triggerstringrequiredOne of
schedule,event,manual.trigger_textstringrequiredstarted_byFlagPerson or nullrequiredWho pressed Run now; null for a schedule or an event.
Show 4 child fieldsHide child fields
idstringrequirednamestringrequiredemailstringrequiredavatar_urlstring or nullrequired
started_atstringrequiredfinished_atstring or nullrequiredsecondsintegerrequiredFrom start to finish, or so far.
deploymentobjectrequiredShow 2 child fieldsHide child fields
idstringrequiredshastring or nullrequired
inputobjectrequiredThe JSON it started with.
outputobjectrequiredWhat the workflow returned.
errorarray of stringrequiredattemptsstringrequirednext_atstring or nullrequiredWhen the app is called for it next.
stepsarray of WorkflowSteprequiredShow 11 child fieldsHide child fields
namestringrequiredkindstringrequiredOne of
step,sleep,wait.statestringrequiredOne of
running,succeeded,failed,waiting,skipped,canceled.secondsinteger or nullrequiredTime spent running over every attempt; null for one not reached.
detailstringrequirederrorarray of stringrequiredThe last attempt's error: message, then where.
attemptsintegerrequiredretried_byFlagPerson or nullrequiredShow 4 child fieldsHide child fields
idstringrequirednamestringrequiredemailstringrequiredavatar_urlstring or nullrequired
wake_atstring or nullrequiredA sleep's end, or a wait's timeout.
eventstring or nullrequiredWhat a wait waits for.
outputobjectrequiredThe step's result; a wait's is the event's data.
Errors
- 404Not found, or not visible to the caller (the two are indistinguishable on purpose).
Every code is explained in Errors.
curl "https://api.theorbits.app/v1/teams/my-team/projects/my-app/workflows" \
-H "Authorization: Bearer $ORBITS_TOKEN"{
"workflows": [
{
"name": "my-app",
"description": "description",
"schedule": null,
"event": null,
"retries": 1,
"trigger_text": "trigger-text",
"last_run": {
"id": "id",
"state": "running",
"at": "2026-11-10T09:30:00Z"
},
"success_rate": null
}
],
"runs": [
{
"id": "id",
"workflow": "sync-stock",
"state": "running",
"trigger": "schedule",
"trigger_text": "Every 15 minutes",
"started_by": {
"id": "id",
"name": "my-app",
"email": "ada@example.com",
"avatar_url": "https://my-app.theorbits.app"
},
"started_at": "2026-11-10T09:30:00Z",
"finished_at": "2026-11-10T09:30:00Z",
"seconds": 1,
"deployment": {
"id": "id",
"sha": null
},
"input": null,
"output": null,
"error": [
"error"
],
"attempts": "3 on step 3",
"next_at": "2026-11-10T09:30:00Z",
"steps": [
{
"name": "update-inventory",
"kind": "step",
"state": "running",
"seconds": null,
"detail": "Gave up after 3 attempts",
"error": [
"error"
],
"attempts": 1,
"retried_by": {
"id": null,
"name": null,
"email": null,
"avatar_url": null
},
"wake_at": "2026-11-10T09:30:00Z",
"event": null,
"output": null
}
]
}
]
}Run a workflow now
Starts a run on the production deployment with input (any JSON, 256 KB at most), as Run now does. The builder picks it up within seconds.
Permissions: Owners, admins and members. Viewers get 403. 404 when the production deployment doesn't list the workflow; 409 without a production deployment.
Headers
AuthorizationstringrequiredBearerand your API token:Bearer orb_live_….Idempotency-KeystringrequiredA new value, such as a UUID, for each change. Resend with the same value and body to retry safely.
From 8 to 128 characters.
Path parameters
teamstringrequiredTeam slug or
team_id.projectstringrequiredProject slug or
prj_id.workflowstringrequired
Body
application/jsoninputobjectAny JSON.
Response 201
The run.idstringrequiredworkflowstringrequiredstatestringrequiredOne of
running,succeeded,failed,canceled.triggerstringrequiredOne of
schedule,event,manual.trigger_textstringrequiredstarted_byFlagPerson or nullrequiredWho pressed Run now; null for a schedule or an event.
Show 4 child fieldsHide child fields
idstringrequirednamestringrequiredemailstringrequiredavatar_urlstring or nullrequired
started_atstringrequiredfinished_atstring or nullrequiredsecondsintegerrequiredFrom start to finish, or so far.
deploymentobjectrequiredShow 2 child fieldsHide child fields
idstringrequiredshastring or nullrequired
inputobjectrequiredThe JSON it started with.
outputobjectrequiredWhat the workflow returned.
errorarray of stringrequiredattemptsstringrequirednext_atstring or nullrequiredWhen the app is called for it next.
stepsarray of WorkflowSteprequiredShow 11 child fieldsHide child fields
namestringrequiredkindstringrequiredOne of
step,sleep,wait.statestringrequiredOne of
running,succeeded,failed,waiting,skipped,canceled.secondsinteger or nullrequiredTime spent running over every attempt; null for one not reached.
detailstringrequirederrorarray of stringrequiredThe last attempt's error: message, then where.
attemptsintegerrequiredretried_byFlagPerson or nullrequiredShow 4 child fieldsHide child fields
idstringrequirednamestringrequiredemailstringrequiredavatar_urlstring or nullrequired
wake_atstring or nullrequiredA sleep's end, or a wait's timeout.
eventstring or nullrequiredWhat a wait waits for.
outputobjectrequiredThe step's result; a wait's is the event's data.
Errors
- 403Authenticated but not allowed in this team.
- 404Not found, or not visible to the caller (the two are indistinguishable on purpose).
- 409The request conflicts with current state.
- 422Validation failed, or the Idempotency-Key was reused with a different body.
Every code is explained in Errors.
curl -X POST "https://api.theorbits.app/v1/teams/my-team/projects/my-app/workflows/send-welcome-email/runs" \
-H "Authorization: Bearer $ORBITS_TOKEN" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"input": null
}'{
"id": "id",
"workflow": "sync-stock",
"state": "running",
"trigger": "schedule",
"trigger_text": "Every 15 minutes",
"started_by": {
"id": "id",
"name": "my-app",
"email": "ada@example.com",
"avatar_url": "https://my-app.theorbits.app"
},
"started_at": "2026-11-10T09:30:00Z",
"finished_at": "2026-11-10T09:30:00Z",
"seconds": 1,
"deployment": {
"id": "id",
"sha": null
},
"input": null,
"output": null,
"error": [
"error"
],
"attempts": "3 on step 3",
"next_at": "2026-11-10T09:30:00Z",
"steps": [
{
"name": "update-inventory",
"kind": "step",
"state": "running",
"seconds": null,
"detail": "Gave up after 3 attempts",
"error": [
"error"
],
"attempts": 1,
"retried_by": {
"id": "id",
"name": "my-app",
"email": "ada@example.com",
"avatar_url": "https://my-app.theorbits.app"
},
"wake_at": "2026-11-10T09:30:00Z",
"event": null,
"output": null
}
]
}One run and its steps
Permissions: Any team member.
Headers
AuthorizationstringrequiredBearerand your API token:Bearer orb_live_….
Path parameters
teamstringrequiredTeam slug or
team_id.projectstringrequiredProject slug or
prj_id.runstringrequired
Response 200
The run.idstringrequiredworkflowstringrequiredstatestringrequiredOne of
running,succeeded,failed,canceled.triggerstringrequiredOne of
schedule,event,manual.trigger_textstringrequiredstarted_byFlagPerson or nullrequiredWho pressed Run now; null for a schedule or an event.
Show 4 child fieldsHide child fields
idstringrequirednamestringrequiredemailstringrequiredavatar_urlstring or nullrequired
started_atstringrequiredfinished_atstring or nullrequiredsecondsintegerrequiredFrom start to finish, or so far.
deploymentobjectrequiredShow 2 child fieldsHide child fields
idstringrequiredshastring or nullrequired
inputobjectrequiredThe JSON it started with.
outputobjectrequiredWhat the workflow returned.
errorarray of stringrequiredattemptsstringrequirednext_atstring or nullrequiredWhen the app is called for it next.
stepsarray of WorkflowSteprequiredShow 11 child fieldsHide child fields
namestringrequiredkindstringrequiredOne of
step,sleep,wait.statestringrequiredOne of
running,succeeded,failed,waiting,skipped,canceled.secondsinteger or nullrequiredTime spent running over every attempt; null for one not reached.
detailstringrequirederrorarray of stringrequiredThe last attempt's error: message, then where.
attemptsintegerrequiredretried_byFlagPerson or nullrequiredShow 4 child fieldsHide child fields
idstringrequirednamestringrequiredemailstringrequiredavatar_urlstring or nullrequired
wake_atstring or nullrequiredA sleep's end, or a wait's timeout.
eventstring or nullrequiredWhat a wait waits for.
outputobjectrequiredThe step's result; a wait's is the event's data.
Errors
- 404Not found, or not visible to the caller (the two are indistinguishable on purpose).
Every code is explained in Errors.
curl "https://api.theorbits.app/v1/teams/my-team/projects/my-app/workflows/runs/run_01jc8x6e4mq2v7r9y3t5b0zp8w" \
-H "Authorization: Bearer $ORBITS_TOKEN"{
"id": "id",
"workflow": "sync-stock",
"state": "running",
"trigger": "schedule",
"trigger_text": "Every 15 minutes",
"started_by": {
"id": "id",
"name": "my-app",
"email": "ada@example.com",
"avatar_url": "https://my-app.theorbits.app"
},
"started_at": "2026-11-10T09:30:00Z",
"finished_at": "2026-11-10T09:30:00Z",
"seconds": 1,
"deployment": {
"id": "id",
"sha": null
},
"input": null,
"output": null,
"error": [
"error"
],
"attempts": "3 on step 3",
"next_at": "2026-11-10T09:30:00Z",
"steps": [
{
"name": "update-inventory",
"kind": "step",
"state": "running",
"seconds": null,
"detail": "Gave up after 3 attempts",
"error": [
"error"
],
"attempts": 1,
"retried_by": {
"id": "id",
"name": "my-app",
"email": "ada@example.com",
"avatar_url": "https://my-app.theorbits.app"
},
"wake_at": "2026-11-10T09:30:00Z",
"event": null,
"output": null
}
]
}Cancel a running run
The app isn't called for it again; a step already running finishes, and its result is dropped. 409 for a run that isn't running.
Permissions: Owners, admins and members.
Headers
AuthorizationstringrequiredBearerand your API token:Bearer orb_live_….Idempotency-KeystringrequiredA new value, such as a UUID, for each change. Resend with the same value and body to retry safely.
From 8 to 128 characters.
Path parameters
teamstringrequiredTeam slug or
team_id.projectstringrequiredProject slug or
prj_id.runstringrequired
Response 200
The run.idstringrequiredworkflowstringrequiredstatestringrequiredOne of
running,succeeded,failed,canceled.triggerstringrequiredOne of
schedule,event,manual.trigger_textstringrequiredstarted_byFlagPerson or nullrequiredWho pressed Run now; null for a schedule or an event.
Show 4 child fieldsHide child fields
idstringrequirednamestringrequiredemailstringrequiredavatar_urlstring or nullrequired
started_atstringrequiredfinished_atstring or nullrequiredsecondsintegerrequiredFrom start to finish, or so far.
deploymentobjectrequiredShow 2 child fieldsHide child fields
idstringrequiredshastring or nullrequired
inputobjectrequiredThe JSON it started with.
outputobjectrequiredWhat the workflow returned.
errorarray of stringrequiredattemptsstringrequirednext_atstring or nullrequiredWhen the app is called for it next.
stepsarray of WorkflowSteprequiredShow 11 child fieldsHide child fields
namestringrequiredkindstringrequiredOne of
step,sleep,wait.statestringrequiredOne of
running,succeeded,failed,waiting,skipped,canceled.secondsinteger or nullrequiredTime spent running over every attempt; null for one not reached.
detailstringrequirederrorarray of stringrequiredThe last attempt's error: message, then where.
attemptsintegerrequiredretried_byFlagPerson or nullrequiredShow 4 child fieldsHide child fields
idstringrequirednamestringrequiredemailstringrequiredavatar_urlstring or nullrequired
wake_atstring or nullrequiredA sleep's end, or a wait's timeout.
eventstring or nullrequiredWhat a wait waits for.
outputobjectrequiredThe step's result; a wait's is the event's data.
Errors
- 403Authenticated but not allowed in this team.
- 404Not found, or not visible to the caller (the two are indistinguishable on purpose).
- 409The request conflicts with current state.
Every code is explained in Errors.
curl -X POST "https://api.theorbits.app/v1/teams/my-team/projects/my-app/workflows/runs/run_01jc8x6e4mq2v7r9y3t5b0zp8w/cancel" \
-H "Authorization: Bearer $ORBITS_TOKEN" \
-H "Idempotency-Key: $(uuidgen)"{
"id": "id",
"workflow": "sync-stock",
"state": "running",
"trigger": "schedule",
"trigger_text": "Every 15 minutes",
"started_by": {
"id": "id",
"name": "my-app",
"email": "ada@example.com",
"avatar_url": "https://my-app.theorbits.app"
},
"started_at": "2026-11-10T09:30:00Z",
"finished_at": "2026-11-10T09:30:00Z",
"seconds": 1,
"deployment": {
"id": "id",
"sha": null
},
"input": null,
"output": null,
"error": [
"error"
],
"attempts": "3 on step 3",
"next_at": "2026-11-10T09:30:00Z",
"steps": [
{
"name": "update-inventory",
"kind": "step",
"state": "running",
"seconds": null,
"detail": "Gave up after 3 attempts",
"error": [
"error"
],
"attempts": 1,
"retried_by": {
"id": "id",
"name": "my-app",
"email": "ada@example.com",
"avatar_url": "https://my-app.theorbits.app"
},
"wake_at": "2026-11-10T09:30:00Z",
"event": null,
"output": null
}
]
}Retry a failed run from the step that failed
The steps before the failed one keep their results; the failed one runs again with a fresh set of attempts, and the run goes on from there. 409 for a run that didn't fail.
Permissions: Owners, admins and members.
Headers
AuthorizationstringrequiredBearerand your API token:Bearer orb_live_….Idempotency-KeystringrequiredA new value, such as a UUID, for each change. Resend with the same value and body to retry safely.
From 8 to 128 characters.
Path parameters
teamstringrequiredTeam slug or
team_id.projectstringrequiredProject slug or
prj_id.runstringrequired
Response 200
The run.idstringrequiredworkflowstringrequiredstatestringrequiredOne of
running,succeeded,failed,canceled.triggerstringrequiredOne of
schedule,event,manual.trigger_textstringrequiredstarted_byFlagPerson or nullrequiredWho pressed Run now; null for a schedule or an event.
Show 4 child fieldsHide child fields
idstringrequirednamestringrequiredemailstringrequiredavatar_urlstring or nullrequired
started_atstringrequiredfinished_atstring or nullrequiredsecondsintegerrequiredFrom start to finish, or so far.
deploymentobjectrequiredShow 2 child fieldsHide child fields
idstringrequiredshastring or nullrequired
inputobjectrequiredThe JSON it started with.
outputobjectrequiredWhat the workflow returned.
errorarray of stringrequiredattemptsstringrequirednext_atstring or nullrequiredWhen the app is called for it next.
stepsarray of WorkflowSteprequiredShow 11 child fieldsHide child fields
namestringrequiredkindstringrequiredOne of
step,sleep,wait.statestringrequiredOne of
running,succeeded,failed,waiting,skipped,canceled.secondsinteger or nullrequiredTime spent running over every attempt; null for one not reached.
detailstringrequirederrorarray of stringrequiredThe last attempt's error: message, then where.
attemptsintegerrequiredretried_byFlagPerson or nullrequiredShow 4 child fieldsHide child fields
idstringrequirednamestringrequiredemailstringrequiredavatar_urlstring or nullrequired
wake_atstring or nullrequiredA sleep's end, or a wait's timeout.
eventstring or nullrequiredWhat a wait waits for.
outputobjectrequiredThe step's result; a wait's is the event's data.
Errors
- 403Authenticated but not allowed in this team.
- 404Not found, or not visible to the caller (the two are indistinguishable on purpose).
- 409The request conflicts with current state.
Every code is explained in Errors.
curl -X POST "https://api.theorbits.app/v1/teams/my-team/projects/my-app/workflows/runs/run_01jc8x6e4mq2v7r9y3t5b0zp8w/retry" \
-H "Authorization: Bearer $ORBITS_TOKEN" \
-H "Idempotency-Key: $(uuidgen)"{
"id": "id",
"workflow": "sync-stock",
"state": "running",
"trigger": "schedule",
"trigger_text": "Every 15 minutes",
"started_by": {
"id": "id",
"name": "my-app",
"email": "ada@example.com",
"avatar_url": "https://my-app.theorbits.app"
},
"started_at": "2026-11-10T09:30:00Z",
"finished_at": "2026-11-10T09:30:00Z",
"seconds": 1,
"deployment": {
"id": "id",
"sha": null
},
"input": null,
"output": null,
"error": [
"error"
],
"attempts": "3 on step 3",
"next_at": "2026-11-10T09:30:00Z",
"steps": [
{
"name": "update-inventory",
"kind": "step",
"state": "running",
"seconds": null,
"detail": "Gave up after 3 attempts",
"error": [
"error"
],
"attempts": 1,
"retried_by": {
"id": "id",
"name": "my-app",
"email": "ada@example.com",
"avatar_url": "https://my-app.theorbits.app"
},
"wake_at": "2026-11-10T09:30:00Z",
"event": null,
"output": null
}
]
}