Running a Workflow

A workflow can stream its result on the connection that started it, or run independently of that connection. Those are the synchronous and asynchronous execute endpoints. Use the asynchronous endpoint for production integrations. The run is unaffected if your client disconnects, its result is always stored, and you can attach to it, cancel it, or come back to it later.

	Synchronous	Asynchronous
Endpoint	`POST /v1/workflow/execute`	`POST /v1/workflow/execute/async`
Returns	An SSE stream of the whole run	An `execution_id`, immediately
If your connection drops	The run is cancelled	The run continues
Result stored	Only with `persistence_mode: "enabled"`	Always
How you read the result	From the stream	Retrieve the run, or attach to its event stream
Cancel	Close the connection	Call the cancel endpoint

The synchronous endpoint is still the shortest path to a first result, so the Workflows quickstart uses it. Reach for the asynchronous endpoint as soon as a run has to survive a dropped connection, a page reload, or a deploy of your own service.

Submit a run

POST /v1/workflow/execute/async takes the same body as the synchronous endpoint — a template (inline or a stored template id), input, time_range, and model_name — and returns 202 Accepted straight away.

import requests

headers = {"X-API-KEY": my_api_key, "Content-Type": "application/json"}

resp = requests.post(
    "https://agents.bigdata.com/v1/workflow/execute/async",
    headers=headers,
    json={
        "template": template_id,
        "input": {"company_id": "D8442A"},
        "time_range": "last_30_days",
        "model_name": "base",
    },
    timeout=30,
)
resp.raise_for_status()
submitted = resp.json()

execution_id = submitted["execution_id"]
print(submitted["status"])   # pending

The execution_id is the handle for everything that follows: reading the result, attaching to the event stream, cancelling, and resuming the run if it stops early. Store it: nothing else identifies the run.

persistence_mode is not accepted here. Every submitted run is stored, because the stored run is how you read its result once the request that started it has returned. See Stored runs and retention below.

Read the result

Retrieve the run with GET /v1/workflow/executions/{execution_id} and check its status. A run is finished when its status is completed, error, or cancelled; while it is pending or running, its events are null.

import time

TERMINAL = {"completed", "error", "cancelled"}


def wait_for_run(execution_id: str, timeout_s: float = 1800.0) -> dict:
    url = f"https://agents.bigdata.com/v1/workflow/executions/{execution_id}"
    deadline = time.monotonic() + timeout_s
    delay = 2.0

    while time.monotonic() < deadline:
        run = requests.get(url, headers={"X-API-KEY": my_api_key}, timeout=30).json()
        if run["status"] in TERMINAL:
            return run
        time.sleep(delay)
        delay = min(delay * 1.5, 30.0)

    raise TimeoutError(f"{execution_id} did not finish in time")


run = wait_for_run(execution_id)

answer = "".join(
    event["content"] for event in run["events"] or [] if event["type"] == "ANSWER"
)
print(answer)

The events list is the run’s streamed messages replayed in order, using the same message types you get live. A handler written for the live stream replays a stored run without changes. See Streaming responses for the full set, and Execution history for the rest of the retrieval response.

Watch a run live

Polling is enough for most integrations. If you want to show progress as it happens — the research plan filling in, the answer arriving token by token — attach to the run’s event stream: GET /v1/workflow/execute/async/{execution_id}/stream

import json

url = f"https://agents.bigdata.com/v1/workflow/execute/async/{execution_id}/stream"

with requests.get(url, headers={"X-API-KEY": my_api_key}, stream=True, timeout=None) as r:
    r.raise_for_status()
    for raw_line in r.iter_lines(decode_unicode=True):
        if not raw_line or not raw_line.startswith("data: "):
            continue
        event = json.loads(raw_line[6:])
        delta = event.get("delta", {})
        if delta.get("type") == "ANSWER":
            print(delta.get("content", ""), end="", flush=True)

The run proceeds whether or not anything is listening, and disconnecting does not stop it. You can attach after the run has already produced output and still receive everything from the start.

Resume a dropped stream

Every event on this stream carries an SSE id. If the connection drops, reconnect to the same URL and send the last id you received in the standard Last-Event-ID header. Delivery continues from that point instead of replaying the run from the beginning.

headers = {"X-API-KEY": my_api_key}
if last_event_id is not None:
    headers["Last-Event-ID"] = last_event_id

A browser EventSource client does this for you: it tracks the last id and sends the header on reconnect automatically.

A run that had begun answering and then starts its answer again emits a STREAM_ROLLBACK event telling you which events to discard. Handle it if you render answer text as it arrives — see STREAM_ROLLBACK.

Cancel a run

POST /v1/workflow/execute/async/{execution_id}/cancel stops a running workflow. The response reports the run’s status once the cancellation was applied, so you do not need to poll afterwards.

resp = requests.post(
    f"https://agents.bigdata.com/v1/workflow/execute/async/{execution_id}/cancel",
    headers={"X-API-KEY": my_api_key},
    timeout=30,
)
print(resp.json()["status"])   # cancelled

Cancelling is safe to repeat. A run that finished while your request was in flight reports completed or error instead of cancelled. A cancelled run keeps whatever it had produced, and you can continue it later.

Continue a run that stopped early

A run that stopped before it finished — one you cancelled, or one that ended in an error — can be continued from where it stopped. Pass its execution_id in the submit body:

resp = requests.post(
    "https://agents.bigdata.com/v1/workflow/execute/async",
    headers=headers,
    json={"template": template_id, "execution_id": execution_id},
    timeout=30,
)

The run picks up from its last saved point rather than starting over, and keeps the same execution_id.

This is a resume, not a follow-up turn. A run that is still pending or running cannot be continued, and neither can one that already completed. Both return 409. To start another piece of research, submit a new run.

Stored runs and retention

Every submitted run is stored, so you decide how long to keep it. List your runs, retrieve any one of them, and delete the ones you no longer need:

GET /v1/workflow/executions — your runs, newest first
GET /v1/workflow/executions/{execution_id} — one run with its full result
DELETE /v1/workflow/executions/{execution_id} — remove a run permanently

Deleting a run that is still in progress stops it first. There is no undo. Execution history covers these endpoints in full.

Error responses

Alongside the usual HTTP errors, the stream and cancel endpoints share one error contract:

Status	Meaning	What to do
`404`	No such execution, or it is not yours.	Check the `execution_id`. Do not retry.
`409`	The run has already finished, so there is nothing to attach to or cancel.	Read the result from `GET /v1/workflow/executions/{execution_id}`.
`503`	The run was accepted but is not ready to act on yet.	Transient. Retry the same request after the number of seconds in the `Retry-After` header.

On submit, 409 means something different: the execution_id you asked to continue cannot be continued, because it is still in progress or has already completed.

Next steps

Execution history

List, retrieve, and delete your stored runs.

Streaming responses

Every message type the stream can emit, and a handler that dispatches on type.

Creating templates

Template anatomy, input placeholders, content filters, and research plans.

Conversation continuity

How execution_id compares with Research Agent chats and checkpoints.

How to guides

Research Service

Search Service

Proprietary Content

Knowledge Graph

Submit a run

Read the result

Watch a run live

Resume a dropped stream

Cancel a run

Continue a run that stopped early

Stored runs and retention

Error responses

Next steps

Execution history

Streaming responses

Creating templates

Conversation continuity

​Submit a run

​Read the result

​Watch a run live

​Resume a dropped stream

​Cancel a run

​Continue a run that stopped early

​Stored runs and retention

​Error responses

​Next steps

Execution history

Streaming responses

Creating templates

Conversation continuity

Submit a run

Read the result

Watch a run live

Resume a dropped stream

Cancel a run

Continue a run that stopped early

Stored runs and retention

Error responses

Next steps