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

# Runs

> Execute workflows and read their results with the Noxus SDK runs service

Once you've built and saved a workflow (see [Building Workflows](/sdk/workflows/building-workflows)), you execute it and read its results either from the definition object or through `client.runs`. This page covers both.

## Running a workflow

Two ways to execute:

**1. From the definition object → a `Run` you poll or stream**

```python theme={null}
wf = client.workflows.get(workflow_id)
run = wf.run({"Input 1": "hello"})               # -> Run (queued)
result = run.wait(output_only=True)              # blocks (polls every 5s), returns output
# or step through progress events:
for event in wf.run_and_stream({"Input 1": "hello"}):
    print(event)
```

**2. Synchronous one-shot via the runs service**

```python theme={null}
out = client.runs.run_sync(workflow_id, {"Input 1": "hello"}, output_only=True)
```

`body`/`input` is a dict keyed by the workflow's input labels.

<Note>
  For input formats (node labels, node IDs, files), streaming, and webhook
  callbacks, see [Running Workflows](/sdk/workflows/running-workflows).
</Note>

## The runs service

```python theme={null}
client.runs.list(workflow_id, page=1, page_size=10)      # -> list[Run]
client.runs.get(workflow_id, run_id)                     # -> Run
client.runs.run_sync(workflow_id, input, output_only=False)
client.runs.stop(run_id)                                 # -> Run (cancel)
client.runs.get_data(run_id, fetch_structured_data=True) # full run payload
client.runs.get_node_io(run_id, node_id, it=0)           # a node's inputs/outputs
client.runs.search("invoice", limit=10, exact=True, search_in=None)  # search across runs
```

## The `Run` object

<Info>
  Fields: `id`, `status`, `progress`, `progress_details`, `workflow_id`, `input`,
  `output`, `created_at`, `finished_at`.
</Info>

Methods (each with an `a`-prefixed async twin):

```python theme={null}
run.wait(interval=5, output_only=False)   # poll until terminal; returns Run or output dict
run.get_status()                          # -> str
run.refresh()                             # re-fetch
run.stop()                                # cancel
run.data(fetch_structured_data=True)      # full payload
for event in run.stream(etag=None):       # live RunEvents
    print(event)
```

`wait(output_only=True)` returns just the output dict; otherwise it returns the refreshed `Run`. Streaming yields `RunEvent`s as the run progresses.