OrbitsDocs
esc
    Open Orbits
    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

    • idstringrequired
    • workflowstringrequired
    • statestringrequired

      One of running, succeeded, failed, canceled.

    • triggerstringrequired

      One of schedule, event, manual.

    • trigger_textstringrequired
    • started_byFlagPerson or nullrequired

      Who pressed Run now; null for a schedule or an event.

      Show 4 child fields
      • idstringrequired
      • namestringrequired
      • emailstringrequired
      • avatar_urlstring or nullrequired
    • started_atstringrequired
    • finished_atstring or nullrequired
    • secondsintegerrequired

      From start to finish, or so far.

    • deploymentobjectrequired
      Show 2 child fields
      • idstringrequired
      • shastring or nullrequired
    • inputobjectrequired

      The JSON it started with.

    • outputobjectrequired

      What the workflow returned.

    • errorarray of stringrequired
    • attemptsstringrequired
    • next_atstring or nullrequired

      When the app is called for it next.

    • stepsarray of WorkflowSteprequired
      Show 11 child fields
      • namestringrequired
      • kindstringrequired

        One of step, sleep, wait.

      • statestringrequired

        One of running, succeeded, failed, waiting, skipped, canceled.

      • secondsinteger or nullrequired

        Time spent running over every attempt; null for one not reached.

      • detailstringrequired
      • errorarray of stringrequired

        The last attempt's error: message, then where.

      • attemptsintegerrequired
      • retried_byFlagPerson or nullrequired
        Show 4 child fields
        • idstringrequired
        • namestringrequired
        • emailstringrequired
        • avatar_urlstring or nullrequired
      • wake_atstring or nullrequired

        A sleep's end, or a wait's timeout.

      • eventstring or nullrequired

        What a wait waits for.

      • outputobjectrequired

        The 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.

    GET/v1/teams/{team}/projects/{project}/workflows
    Read or full tokenReturns200OK

    Headers

    • Authorizationstringrequired

      Bearer and your API token: Bearer orb_live_….

    Path parameters

    • teamstringrequired

      Team slug or team_ id.

    • projectstringrequired

      Project slug or prj_ id.

    Response 200

    The workflows and runs.
    • workflowsarray of objectrequired
      Show 8 child fields
      • namestringrequired
      • descriptionstringrequired
      • schedulestring or nullrequired

        Five-field cron, in UTC.

      • eventstring or nullrequired
      • retriesintegerrequired

        Attempts after the first, for each step.

      • trigger_textstringrequired
      • last_runnull or objectrequired
        Show 3 child fields
        • idstringrequired
        • statestringrequired

          One of running, succeeded, failed, canceled.

        • atstringrequired
      • success_ratenumber or nullrequired

        From 0 to 1.

    • runsarray of WorkflowRunrequired
      Show 16 child fields
      • idstringrequired
      • workflowstringrequired
      • statestringrequired

        One of running, succeeded, failed, canceled.

      • triggerstringrequired

        One of schedule, event, manual.

      • trigger_textstringrequired
      • started_byFlagPerson or nullrequired

        Who pressed Run now; null for a schedule or an event.

        Show 4 child fields
        • idstringrequired
        • namestringrequired
        • emailstringrequired
        • avatar_urlstring or nullrequired
      • started_atstringrequired
      • finished_atstring or nullrequired
      • secondsintegerrequired

        From start to finish, or so far.

      • deploymentobjectrequired
        Show 2 child fields
        • idstringrequired
        • shastring or nullrequired
      • inputobjectrequired

        The JSON it started with.

      • outputobjectrequired

        What the workflow returned.

      • errorarray of stringrequired
      • attemptsstringrequired
      • next_atstring or nullrequired

        When the app is called for it next.

      • stepsarray of WorkflowSteprequired
        Show 11 child fields
        • namestringrequired
        • kindstringrequired

          One of step, sleep, wait.

        • statestringrequired

          One of running, succeeded, failed, waiting, skipped, canceled.

        • secondsinteger or nullrequired

          Time spent running over every attempt; null for one not reached.

        • detailstringrequired
        • errorarray of stringrequired

          The last attempt's error: message, then where.

        • attemptsintegerrequired
        • retried_byFlagPerson or nullrequired
          Show 4 child fields
          • idstringrequired
          • namestringrequired
          • emailstringrequired
          • avatar_urlstring or nullrequired
        • wake_atstring or nullrequired

          A sleep's end, or a wait's timeout.

        • eventstring or nullrequired

          What a wait waits for.

        • outputobjectrequired

          The 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"
    Response 200
    {
      "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.

    POST/v1/teams/{team}/projects/{project}/workflows/{workflow}/runs
    Full tokenNeeds Idempotency-KeyReturns201Created

    Headers

    • Authorizationstringrequired

      Bearer and your API token: Bearer orb_live_….

    • Idempotency-Keystringrequired

      A 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

    • teamstringrequired

      Team slug or team_ id.

    • projectstringrequired

      Project slug or prj_ id.

    • workflowstringrequired

    Body

    application/json
    • inputobject

      Any JSON.

    Response 201

    The run.
    • idstringrequired
    • workflowstringrequired
    • statestringrequired

      One of running, succeeded, failed, canceled.

    • triggerstringrequired

      One of schedule, event, manual.

    • trigger_textstringrequired
    • started_byFlagPerson or nullrequired

      Who pressed Run now; null for a schedule or an event.

      Show 4 child fields
      • idstringrequired
      • namestringrequired
      • emailstringrequired
      • avatar_urlstring or nullrequired
    • started_atstringrequired
    • finished_atstring or nullrequired
    • secondsintegerrequired

      From start to finish, or so far.

    • deploymentobjectrequired
      Show 2 child fields
      • idstringrequired
      • shastring or nullrequired
    • inputobjectrequired

      The JSON it started with.

    • outputobjectrequired

      What the workflow returned.

    • errorarray of stringrequired
    • attemptsstringrequired
    • next_atstring or nullrequired

      When the app is called for it next.

    • stepsarray of WorkflowSteprequired
      Show 11 child fields
      • namestringrequired
      • kindstringrequired

        One of step, sleep, wait.

      • statestringrequired

        One of running, succeeded, failed, waiting, skipped, canceled.

      • secondsinteger or nullrequired

        Time spent running over every attempt; null for one not reached.

      • detailstringrequired
      • errorarray of stringrequired

        The last attempt's error: message, then where.

      • attemptsintegerrequired
      • retried_byFlagPerson or nullrequired
        Show 4 child fields
        • idstringrequired
        • namestringrequired
        • emailstringrequired
        • avatar_urlstring or nullrequired
      • wake_atstring or nullrequired

        A sleep's end, or a wait's timeout.

      • eventstring or nullrequired

        What a wait waits for.

      • outputobjectrequired

        The 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
      }'
    Response 201
    {
      "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.

    GET/v1/teams/{team}/projects/{project}/workflows/runs/{run}
    Read or full tokenReturns200OK

    Headers

    • Authorizationstringrequired

      Bearer and your API token: Bearer orb_live_….

    Path parameters

    • teamstringrequired

      Team slug or team_ id.

    • projectstringrequired

      Project slug or prj_ id.

    • runstringrequired

    Response 200

    The run.
    • idstringrequired
    • workflowstringrequired
    • statestringrequired

      One of running, succeeded, failed, canceled.

    • triggerstringrequired

      One of schedule, event, manual.

    • trigger_textstringrequired
    • started_byFlagPerson or nullrequired

      Who pressed Run now; null for a schedule or an event.

      Show 4 child fields
      • idstringrequired
      • namestringrequired
      • emailstringrequired
      • avatar_urlstring or nullrequired
    • started_atstringrequired
    • finished_atstring or nullrequired
    • secondsintegerrequired

      From start to finish, or so far.

    • deploymentobjectrequired
      Show 2 child fields
      • idstringrequired
      • shastring or nullrequired
    • inputobjectrequired

      The JSON it started with.

    • outputobjectrequired

      What the workflow returned.

    • errorarray of stringrequired
    • attemptsstringrequired
    • next_atstring or nullrequired

      When the app is called for it next.

    • stepsarray of WorkflowSteprequired
      Show 11 child fields
      • namestringrequired
      • kindstringrequired

        One of step, sleep, wait.

      • statestringrequired

        One of running, succeeded, failed, waiting, skipped, canceled.

      • secondsinteger or nullrequired

        Time spent running over every attempt; null for one not reached.

      • detailstringrequired
      • errorarray of stringrequired

        The last attempt's error: message, then where.

      • attemptsintegerrequired
      • retried_byFlagPerson or nullrequired
        Show 4 child fields
        • idstringrequired
        • namestringrequired
        • emailstringrequired
        • avatar_urlstring or nullrequired
      • wake_atstring or nullrequired

        A sleep's end, or a wait's timeout.

      • eventstring or nullrequired

        What a wait waits for.

      • outputobjectrequired

        The 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"
    Response 200
    {
      "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.

    POST/v1/teams/{team}/projects/{project}/workflows/runs/{run}/cancel
    Full tokenNeeds Idempotency-KeyReturns200OK

    Headers

    • Authorizationstringrequired

      Bearer and your API token: Bearer orb_live_….

    • Idempotency-Keystringrequired

      A 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

    • teamstringrequired

      Team slug or team_ id.

    • projectstringrequired

      Project slug or prj_ id.

    • runstringrequired

    Response 200

    The run.
    • idstringrequired
    • workflowstringrequired
    • statestringrequired

      One of running, succeeded, failed, canceled.

    • triggerstringrequired

      One of schedule, event, manual.

    • trigger_textstringrequired
    • started_byFlagPerson or nullrequired

      Who pressed Run now; null for a schedule or an event.

      Show 4 child fields
      • idstringrequired
      • namestringrequired
      • emailstringrequired
      • avatar_urlstring or nullrequired
    • started_atstringrequired
    • finished_atstring or nullrequired
    • secondsintegerrequired

      From start to finish, or so far.

    • deploymentobjectrequired
      Show 2 child fields
      • idstringrequired
      • shastring or nullrequired
    • inputobjectrequired

      The JSON it started with.

    • outputobjectrequired

      What the workflow returned.

    • errorarray of stringrequired
    • attemptsstringrequired
    • next_atstring or nullrequired

      When the app is called for it next.

    • stepsarray of WorkflowSteprequired
      Show 11 child fields
      • namestringrequired
      • kindstringrequired

        One of step, sleep, wait.

      • statestringrequired

        One of running, succeeded, failed, waiting, skipped, canceled.

      • secondsinteger or nullrequired

        Time spent running over every attempt; null for one not reached.

      • detailstringrequired
      • errorarray of stringrequired

        The last attempt's error: message, then where.

      • attemptsintegerrequired
      • retried_byFlagPerson or nullrequired
        Show 4 child fields
        • idstringrequired
        • namestringrequired
        • emailstringrequired
        • avatar_urlstring or nullrequired
      • wake_atstring or nullrequired

        A sleep's end, or a wait's timeout.

      • eventstring or nullrequired

        What a wait waits for.

      • outputobjectrequired

        The 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)"
    Response 200
    {
      "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.

    POST/v1/teams/{team}/projects/{project}/workflows/runs/{run}/retry
    Full tokenNeeds Idempotency-KeyReturns200OK

    Headers

    • Authorizationstringrequired

      Bearer and your API token: Bearer orb_live_….

    • Idempotency-Keystringrequired

      A 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

    • teamstringrequired

      Team slug or team_ id.

    • projectstringrequired

      Project slug or prj_ id.

    • runstringrequired

    Response 200

    The run.
    • idstringrequired
    • workflowstringrequired
    • statestringrequired

      One of running, succeeded, failed, canceled.

    • triggerstringrequired

      One of schedule, event, manual.

    • trigger_textstringrequired
    • started_byFlagPerson or nullrequired

      Who pressed Run now; null for a schedule or an event.

      Show 4 child fields
      • idstringrequired
      • namestringrequired
      • emailstringrequired
      • avatar_urlstring or nullrequired
    • started_atstringrequired
    • finished_atstring or nullrequired
    • secondsintegerrequired

      From start to finish, or so far.

    • deploymentobjectrequired
      Show 2 child fields
      • idstringrequired
      • shastring or nullrequired
    • inputobjectrequired

      The JSON it started with.

    • outputobjectrequired

      What the workflow returned.

    • errorarray of stringrequired
    • attemptsstringrequired
    • next_atstring or nullrequired

      When the app is called for it next.

    • stepsarray of WorkflowSteprequired
      Show 11 child fields
      • namestringrequired
      • kindstringrequired

        One of step, sleep, wait.

      • statestringrequired

        One of running, succeeded, failed, waiting, skipped, canceled.

      • secondsinteger or nullrequired

        Time spent running over every attempt; null for one not reached.

      • detailstringrequired
      • errorarray of stringrequired

        The last attempt's error: message, then where.

      • attemptsintegerrequired
      • retried_byFlagPerson or nullrequired
        Show 4 child fields
        • idstringrequired
        • namestringrequired
        • emailstringrequired
        • avatar_urlstring or nullrequired
      • wake_atstring or nullrequired

        A sleep's end, or a wait's timeout.

      • eventstring or nullrequired

        What a wait waits for.

      • outputobjectrequired

        The 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)"
    Response 200
    {
      "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
        }
      ]
    }

    Was this page helpful?

    Updated