Execution history

You can store a workflow run and retrieve it later. When you turn persistence on, each run is stored under an execution_id. You can then list your runs and fetch any one of them, including its full result, long after the streaming connection has closed. A workflow 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. Persistence and history are a Workflows feature. The Research Agent does not store runs this way.

Enable persistence

A run is stored only when you execute it with persistence_mode set to enabled:

import requests

payload = {
    "template": {"id": "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.

When persistence_mode is left at its default of disabled, the run streams as normal but is not stored. You cannot list or retrieve it afterward.

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.

How to guides

Research Service

Search Service

Proprietary Content

Knowledge Graph

Enable persistence

List executions

Retrieve a single execution

​Enable persistence

​List executions

​Retrieve a single execution

Enable persistence

List executions

Retrieve a single execution