> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bigdata.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Execution history

> Persist workflow runs and retrieve their status, consumption, and full result after the stream closes.

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`:

```python theme={null}
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.

```python theme={null}
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.

```python theme={null}
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](/how-to-guides/agents/concepts/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`.