Execution history

A stored workflow run is kept under its execution_id. You can list your runs, fetch any one of them including its full result long after the streaming connection has closed, and delete the ones you no longer need. A run is stored once and is shared between the API and the Bigdata.com app. A run you start through the API appears in your run history in the app, and a run you start in the app can be retrieved through the API. History is a Workflows feature. The Research Agent does not store runs this way.

Which runs are stored

A run submitted to POST /v1/workflow/execute/async is always stored. That is how you read its result once the submit request has returned. See Running a workflow.
A run streamed from POST /v1/workflow/execute is stored only if you execute it with persistence_mode set to enabled. At its default of disabled the run streams as normal but is not stored, and you cannot list or retrieve it afterward.

import requests

payload = {
    "template": "your-template-id",
    "persistence_mode": "enabled",
}
resp = requests.post(
    "https://agents.bigdata.com/v1/workflow/execute",
    headers={"X-API-KEY": my_api_key, "Content-Type": "application/json"},
    json=payload,
    stream=True,
    timeout=300,
)
# Every streamed event includes the execution_id. Capture it to retrieve the run later.

persistence_mode is fixed for the life of a conversation. A request that resumes an earlier run must pass the same value it was created with, or the server returns 409. See Conversation continuity.

List executions

GET /v1/workflow/executions returns your stored runs, newest first.

resp = requests.get(
    "https://agents.bigdata.com/v1/workflow/executions",
    headers={"X-API-KEY": my_api_key},
)
page = resp.json()
for run in page["results"]:
    print(f"{run['execution_id']}  {run['status']}  {run['name']}")

The response is one page of execution summaries. It has these fields:

results is the list of executions. Each one has execution_id, name, status, template_id, inputs, is_public, date_created, and last_updated.
count is the number of matching executions.
cursor is the pointer to the next page. Pass it back as the cursor query parameter to fetch that page. It is null on the last page.

You can also pass these query parameters. limit sets the page size and defaults to 20. cursor fetches the next page. template_id lists only the runs of one template.

Retrieve a single execution

GET /v1/workflow/executions/{execution_id} returns one run with its full result. Use this to retrieve a run’s output after the streaming connection has closed.

resp = requests.get(
    f"https://agents.bigdata.com/v1/workflow/executions/{execution_id}",
    headers={"X-API-KEY": my_api_key},
)
run = resp.json()

print(run["status"])            # pending | running | completed | error | cancelled
print(run["consumption"])       # resource usage breakdown for the run

# `events` is the run's streamed messages, replayed in order. These are the same
# message types you get live during execution, such as answer, grounding, and charts.
for event in run["events"] or []:
    if event["type"] == "ANSWER":
        print(event["content"], end="")

The events list uses the same message types documented in Streaming responses. The handler you use for a live stream can therefore replay a stored run without change. events is null while a run is still pending or running.

Delete an execution

DELETE /v1/workflow/executions/{execution_id} removes a run and its result permanently, and returns 204 No Content. Use it to decide how long your runs are kept.

resp = requests.delete(
    f"https://agents.bigdata.com/v1/workflow/executions/{execution_id}",
    headers={"X-API-KEY": my_api_key},
)
resp.raise_for_status()

Deleting a run that is still in progress stops it first. A run that does not exist, or one you do not own, returns 404. There is no undo.

Next steps

Running a workflow

Submit a run that outlives your connection, watch it live, and cancel it.

Streaming responses

Every message type a stored events list can contain.

How to guides

Research Service

Search Service

Proprietary Content

Knowledge Graph

Which runs are stored

List executions

Retrieve a single execution

Delete an execution

Next steps

Running a workflow

Streaming responses

​Which runs are stored

​List executions

​Retrieve a single execution

​Delete an execution

​Next steps

Running a workflow

Streaming responses

Which runs are stored

List executions

Retrieve a single execution

Delete an execution

Next steps