Skip to main content
This tutorial shows how to run a Workflows workflow programmatically over HTTPS. You need an API key, your account ID, and a workflow that is already defined and saved in the Workflows UI. You do not need to manage the underlying infrastructure.

Prerequisites

  • A workflow defined and saved in the Workflows UI
  • A Scale API key
  • Your Scale account ID (the account that owns the workflow)
If you are missing credentials, contact your Scale representative.

Authentication

Send requests over HTTPS to your SGP host—the same origin you use to open the Workflows UI. Every example below uses a base URL of the form https://<your-sgp-host>/corp-api/compass/api. Include these headers on each request:
<your-api-key> is your Scale API key. <your-account-id> is the ID of the account that owns the workflow you want to run.

Run and wait

The usual pattern is to start a run, then block until it finishes (up to a configurable timeout). By default, the SGP route to Workflows closes requests after 120 seconds, so use this pattern for runs that finish within two minutes. For longer runs, see Polling instead of blocking.

curl equivalent

API reference

All paths below are relative to BASE_URL (https://<your-sgp-host>/corp-api/compass/api).

POST /v1/workflow/run

Starts a workflow run and returns immediately with a sessionId. Request body:
variables is optional. Values override defaults saved on the workflow and are substituted into ${variable_name} placeholders in your cards. Keys that the workflow does not define are dropped. For typical use cases, use flat string values. Response:

GET /v1/sessions/:sessionId

Returns the current status of a running session. Use this endpoint when you want to poll instead of blocking on the result endpoint. Example response:
Each card also carries startTime and endTime (epoch milliseconds) once they are recorded, and errorMessage when its status is errored. When status is failed, the response includes errorReason: cancelled, timed_out, terminated, card_error, or workflow_error. Session status values Card status values

GET /v1/sessions/:sessionId/result?timeout=<ms>

Waits until the run finishes, then returns the final output. If the run doesn’t finish within timeout milliseconds (default 600000, ten minutes), the request fails with 408. By default, the SGP route to Workflows closes requests after 120 seconds, so a request that waits longer fails with 504 before timeout elapses. For runs over two minutes, poll GET /v1/sessions/:sessionId instead. Query parameters
  • timeout — milliseconds to wait (default 600000)
Example response:
data contains the rows. schema describes the columns. metadata carries the total row count and the run’s duration when they are known.

Polling instead of blocking

If you prefer short requests instead of a long-lived connection, poll GET /v1/sessions/:sessionId until the session is completed, then call GET /v1/sessions/:sessionId/result to fetch the tabular output. The following example reuses the same BASE_URL and HEADERS as in Run and wait.
Polling returns session state (status and card metadata), not the full workflow table. After the session reaches completed, call GET /v1/sessions/:sessionId/result to retrieve the rows.

Workflow variables

Variables let you parameterize a workflow without editing its definition. They replace ${variable_name} placeholders in card configuration (for example, filter values, prompt templates, or model parameters).
Values you pass override defaults saved on the workflow. Any variable you omit uses the workflow’s saved default. Variables that are not saved on the workflow are dropped.

Error handling

Error bodies are JSON. Many errors look like this:
Authentication failures may include both error and message:
This variant parses JSON error bodies from failed responses:
runWorkflowSafe assumes BASE_URL and HEADERS are defined the same way as in Run and wait.