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

# Runs resource

> Async operations for the Valkyrie run lifecycle.

Access these methods through `client.runs`.

<h2 id="start">
  `client.runs.start`
</h2>

Start a run from an uploaded agent name or complete contract.

```python Signature theme={null}
async def start(
    agent: str | AgentContractRequest,
    benchmark: str,
    *,
    model: str | None = None,
    concurrency: int = 5,
    task_ids: Sequence[str] | None = None,
    slice_str: str | None = None,
    dataset: str | None = None,
    label: str | None = None,
    lambda_function: str | None = None,
    provider: str | None = None,
    agent_kwargs: Mapping[str, str] | None = None,
    secrets: Mapping[str, str] | None = None,
    service_headers: Mapping[str, str] | None = None,
    webhook_intervals: Sequence[int] | None = None,
    ignore_custom_services: bool = False,
) -> StartBenchmarkResponse
```

**Parameters**

<div className="border-b border-gray-200 py-3 dark:border-gray-800">
  <div className="flex min-w-0 flex-wrap items-baseline gap-x-2 gap-y-1"><span className="break-all font-mono text-sm">{"agent"}</span><span className="min-w-0 break-words text-sm text-gray-500 dark:text-gray-400">required · str | <a href="/reference/sdk/models/agents#agent-contract-request"><code>AgentContractRequest</code></a></span></div>
</div>

<div className="border-b border-gray-200 py-3 dark:border-gray-800">
  <div className="flex min-w-0 flex-wrap items-baseline gap-x-2 gap-y-1"><span className="break-all font-mono text-sm">{"benchmark"}</span><span className="min-w-0 break-words text-sm text-gray-500 dark:text-gray-400">required · str</span></div>
</div>

<div className="border-b border-gray-200 py-3 dark:border-gray-800">
  <div className="flex min-w-0 flex-wrap items-baseline gap-x-2 gap-y-1"><span className="break-all font-mono text-sm">{"model"}</span><span className="min-w-0 break-words text-sm text-gray-500 dark:text-gray-400">optional · str | None · default: <code>{"None"}</code></span></div>
</div>

<div className="border-b border-gray-200 py-3 dark:border-gray-800">
  <div className="flex min-w-0 flex-wrap items-baseline gap-x-2 gap-y-1"><span className="break-all font-mono text-sm">{"concurrency"}</span><span className="min-w-0 break-words text-sm text-gray-500 dark:text-gray-400">optional · int · default: <code>{"5"}</code></span></div>
</div>

<div className="border-b border-gray-200 py-3 dark:border-gray-800">
  <div className="flex min-w-0 flex-wrap items-baseline gap-x-2 gap-y-1"><span className="break-all font-mono text-sm">{"task_ids"}</span><span className="min-w-0 break-words text-sm text-gray-500 dark:text-gray-400">optional · Sequence\[str] | None · default: <code>{"None"}</code></span></div>
</div>

<div className="border-b border-gray-200 py-3 dark:border-gray-800">
  <div className="flex min-w-0 flex-wrap items-baseline gap-x-2 gap-y-1"><span className="break-all font-mono text-sm">{"slice_str"}</span><span className="min-w-0 break-words text-sm text-gray-500 dark:text-gray-400">optional · str | None · default: <code>{"None"}</code></span></div>
</div>

<div className="border-b border-gray-200 py-3 dark:border-gray-800">
  <div className="flex min-w-0 flex-wrap items-baseline gap-x-2 gap-y-1"><span className="break-all font-mono text-sm">{"dataset"}</span><span className="min-w-0 break-words text-sm text-gray-500 dark:text-gray-400">optional · str | None · default: <code>{"None"}</code></span></div>
</div>

<div className="border-b border-gray-200 py-3 dark:border-gray-800">
  <div className="flex min-w-0 flex-wrap items-baseline gap-x-2 gap-y-1"><span className="break-all font-mono text-sm">{"label"}</span><span className="min-w-0 break-words text-sm text-gray-500 dark:text-gray-400">optional · str | None · default: <code>{"None"}</code></span></div>
</div>

<div className="border-b border-gray-200 py-3 dark:border-gray-800">
  <div className="flex min-w-0 flex-wrap items-baseline gap-x-2 gap-y-1"><span className="break-all font-mono text-sm">{"lambda_function"}</span><span className="min-w-0 break-words text-sm text-gray-500 dark:text-gray-400">optional · str | None · default: <code>{"None"}</code></span></div>
</div>

<div className="border-b border-gray-200 py-3 dark:border-gray-800">
  <div className="flex min-w-0 flex-wrap items-baseline gap-x-2 gap-y-1"><span className="break-all font-mono text-sm">{"provider"}</span><span className="min-w-0 break-words text-sm text-gray-500 dark:text-gray-400">optional · str | None · default: <code>{"None"}</code></span></div>
</div>

<div className="border-b border-gray-200 py-3 dark:border-gray-800">
  <div className="flex min-w-0 flex-wrap items-baseline gap-x-2 gap-y-1"><span className="break-all font-mono text-sm">{"agent_kwargs"}</span><span className="min-w-0 break-words text-sm text-gray-500 dark:text-gray-400">optional · Mapping\[str, str] | None · default: <code>{"None"}</code></span></div>
</div>

<div className="border-b border-gray-200 py-3 dark:border-gray-800">
  <div className="flex min-w-0 flex-wrap items-baseline gap-x-2 gap-y-1"><span className="break-all font-mono text-sm">{"secrets"}</span><span className="min-w-0 break-words text-sm text-gray-500 dark:text-gray-400">optional · Mapping\[str, str] | None · default: <code>{"None"}</code></span></div>
</div>

<div className="border-b border-gray-200 py-3 dark:border-gray-800">
  <div className="flex min-w-0 flex-wrap items-baseline gap-x-2 gap-y-1"><span className="break-all font-mono text-sm">{"service_headers"}</span><span className="min-w-0 break-words text-sm text-gray-500 dark:text-gray-400">optional · Mapping\[str, str] | None · default: <code>{"None"}</code></span></div>
</div>

<div className="border-b border-gray-200 py-3 dark:border-gray-800">
  <div className="flex min-w-0 flex-wrap items-baseline gap-x-2 gap-y-1"><span className="break-all font-mono text-sm">{"webhook_intervals"}</span><span className="min-w-0 break-words text-sm text-gray-500 dark:text-gray-400">optional · Sequence\[int] | None · default: <code>{"None"}</code></span></div>
</div>

<div className="border-b border-gray-200 py-3 dark:border-gray-800">
  <div className="flex min-w-0 flex-wrap items-baseline gap-x-2 gap-y-1"><span className="break-all font-mono text-sm">{"ignore_custom_services"}</span><span className="min-w-0 break-words text-sm text-gray-500 dark:text-gray-400">optional · bool · default: <code>{"False"}</code></span></div>
</div>

**Returns**

<a href="/reference/sdk/models/runs#start-benchmark-response"><code>StartBenchmarkResponse</code></a>

For examples, see the [Python SDK guide](/sdk/runs).

<h2 id="fetch">
  `client.runs.fetch`
</h2>

Fetch the latest state of a run.

```python Signature theme={null}
async def fetch(run_id: UUID) -> FetchBenchmarkResponse
```

**Parameters**

<div className="border-b border-gray-200 py-3 dark:border-gray-800">
  <div className="flex min-w-0 flex-wrap items-baseline gap-x-2 gap-y-1"><span className="break-all font-mono text-sm">{"run_id"}</span><span className="min-w-0 break-words text-sm text-gray-500 dark:text-gray-400">required · UUID</span></div>
</div>

**Returns**

<a href="/reference/sdk/models/runs#fetch-benchmark-response"><code>FetchBenchmarkResponse</code></a>

For examples, see the [Python SDK guide](/sdk/runs).

<h2 id="list">
  `client.runs.list`
</h2>

List runs using typed filters and pagination.

```python Signature theme={null}
async def list(request: FetchBenchmarksRequest | None = None) -> FetchBenchmarksResponse
```

**Parameters**

<div className="border-b border-gray-200 py-3 dark:border-gray-800">
  <div className="flex min-w-0 flex-wrap items-baseline gap-x-2 gap-y-1"><span className="break-all font-mono text-sm">{"request"}</span><span className="min-w-0 break-words text-sm text-gray-500 dark:text-gray-400">optional · <a href="/reference/sdk/models/runs#fetch-benchmarks-request"><code>FetchBenchmarksRequest</code></a> | None · default: <code>{"None"}</code></span></div>
</div>

**Returns**

<a href="/reference/sdk/models/runs#fetch-benchmarks-response"><code>FetchBenchmarksResponse</code></a>

For examples, see the [Python SDK guide](/sdk/runs).

<h2 id="stream">
  `client.runs.stream`
</h2>

Yield typed updates until the run completes or disconnects.

```python Signature theme={null}
async def stream(run_id: UUID) -> AsyncIterator[FetchBenchmarkResponse]
```

**Parameters**

<div className="border-b border-gray-200 py-3 dark:border-gray-800">
  <div className="flex min-w-0 flex-wrap items-baseline gap-x-2 gap-y-1"><span className="break-all font-mono text-sm">{"run_id"}</span><span className="min-w-0 break-words text-sm text-gray-500 dark:text-gray-400">required · UUID</span></div>
</div>

**Returns**

AsyncIterator\[<a href="/reference/sdk/models/runs#fetch-benchmark-response"><code>FetchBenchmarkResponse</code></a>]

For examples, see the [Python SDK guide](/sdk/runs).

<h2 id="results">
  `client.runs.results`
</h2>

Fetch final results or upload them and return S3 links.

```python Overload 1 theme={null}
async def results(
    run_id: UUID,
    *,
    task_ids: Sequence[str] | None = None,
    upload_to_s3: Literal[False] = False,
) -> FinalViewResponse
```

```python Overload 2 theme={null}
async def results(
    run_id: UUID,
    *,
    task_ids: Sequence[str] | None = None,
    upload_to_s3: Literal[True],
) -> S3UploadResultsResponse
```

```python Overload 3 theme={null}
async def results(
    run_id: UUID,
    *,
    task_ids: Sequence[str] | None = None,
    upload_to_s3: bool,
) -> RetrieveResultsResponse
```

**Parameters**

<div className="border-b border-gray-200 py-3 dark:border-gray-800">
  <div className="flex min-w-0 flex-wrap items-baseline gap-x-2 gap-y-1"><span className="break-all font-mono text-sm">{"run_id"}</span><span className="min-w-0 break-words text-sm text-gray-500 dark:text-gray-400">required · UUID</span></div>
</div>

<div className="border-b border-gray-200 py-3 dark:border-gray-800">
  <div className="flex min-w-0 flex-wrap items-baseline gap-x-2 gap-y-1"><span className="break-all font-mono text-sm">{"task_ids"}</span><span className="min-w-0 break-words text-sm text-gray-500 dark:text-gray-400">optional · Sequence\[str] | None · default: <code>{"None"}</code></span></div>
</div>

<div className="border-b border-gray-200 py-3 dark:border-gray-800">
  <div className="flex min-w-0 flex-wrap items-baseline gap-x-2 gap-y-1"><span className="break-all font-mono text-sm">{"upload_to_s3"}</span><span className="min-w-0 break-words text-sm text-gray-500 dark:text-gray-400">optional · bool · default: <code>{"False"}</code></span></div>
</div>

**Returns**

The selected overload determines the return type.

| Overload | Return type                                                                                              |
| -------: | -------------------------------------------------------------------------------------------------------- |
|        1 | <a href="/reference/sdk/models/runs#final-view-response"><code>FinalViewResponse</code></a>              |
|        2 | <a href="/reference/sdk/models/runs#s3-upload-results-response"><code>S3UploadResultsResponse</code></a> |
|        3 | RetrieveResultsResponse                                                                                  |

For examples, see the [Python SDK guide](/sdk/runs).

<h2 id="metadata">
  `client.runs.metadata`
</h2>

Fetch the stored launch metadata for a run.

```python Signature theme={null}
async def metadata(run_id: UUID) -> FetchBenchmarkMetadataResponse
```

**Parameters**

<div className="border-b border-gray-200 py-3 dark:border-gray-800">
  <div className="flex min-w-0 flex-wrap items-baseline gap-x-2 gap-y-1"><span className="break-all font-mono text-sm">{"run_id"}</span><span className="min-w-0 break-words text-sm text-gray-500 dark:text-gray-400">required · UUID</span></div>
</div>

**Returns**

<a href="/reference/sdk/models/runs#fetch-benchmark-metadata-response"><code>FetchBenchmarkMetadataResponse</code></a>

For examples, see the [Python SDK guide](/sdk/runs).

<h2 id="results-exist">
  `client.runs.results_exist`
</h2>

Check whether the canonical result file already exists in S3.

```python Signature theme={null}
async def results_exist(run_id: UUID) -> ResultsExistResponse
```

**Parameters**

<div className="border-b border-gray-200 py-3 dark:border-gray-800">
  <div className="flex min-w-0 flex-wrap items-baseline gap-x-2 gap-y-1"><span className="break-all font-mono text-sm">{"run_id"}</span><span className="min-w-0 break-words text-sm text-gray-500 dark:text-gray-400">required · UUID</span></div>
</div>

**Returns**

<a href="/reference/sdk/models/runs#results-exist-response"><code>ResultsExistResponse</code></a>

For examples, see the [Python SDK guide](/sdk/runs).

<h2 id="analyze">
  `client.runs.analyze`
</h2>

Yield typed progress events while analyzing a finished run.

```python Signature theme={null}
async def analyze(
    run_id: UUID,
    *,
    no_cache: bool = False,
    lambda_function: str | None = None,
) -> AsyncIterator[AnalyzeEvent]
```

**Parameters**

<div className="border-b border-gray-200 py-3 dark:border-gray-800">
  <div className="flex min-w-0 flex-wrap items-baseline gap-x-2 gap-y-1"><span className="break-all font-mono text-sm">{"run_id"}</span><span className="min-w-0 break-words text-sm text-gray-500 dark:text-gray-400">required · UUID</span></div>
</div>

<div className="border-b border-gray-200 py-3 dark:border-gray-800">
  <div className="flex min-w-0 flex-wrap items-baseline gap-x-2 gap-y-1"><span className="break-all font-mono text-sm">{"no_cache"}</span><span className="min-w-0 break-words text-sm text-gray-500 dark:text-gray-400">optional · bool · default: <code>{"False"}</code></span></div>
</div>

<div className="border-b border-gray-200 py-3 dark:border-gray-800">
  <div className="flex min-w-0 flex-wrap items-baseline gap-x-2 gap-y-1"><span className="break-all font-mono text-sm">{"lambda_function"}</span><span className="min-w-0 break-words text-sm text-gray-500 dark:text-gray-400">optional · str | None · default: <code>{"None"}</code></span></div>
</div>

**Returns**

AsyncIterator\[<a href="/reference/sdk/models/runs#analyze-event"><code>AnalyzeEvent</code></a>]

For examples, see the [Python SDK guide](/sdk/runs).

<h2 id="stream-outputs">
  `client.runs.stream_outputs`
</h2>

Yield chunks from the tar archive containing run outputs.

```python Signature theme={null}
async def stream_outputs(run_id: UUID, *, task_ids: Sequence[str] | None = None) -> AsyncIterator[bytes]
```

**Parameters**

<div className="border-b border-gray-200 py-3 dark:border-gray-800">
  <div className="flex min-w-0 flex-wrap items-baseline gap-x-2 gap-y-1"><span className="break-all font-mono text-sm">{"run_id"}</span><span className="min-w-0 break-words text-sm text-gray-500 dark:text-gray-400">required · UUID</span></div>
</div>

<div className="border-b border-gray-200 py-3 dark:border-gray-800">
  <div className="flex min-w-0 flex-wrap items-baseline gap-x-2 gap-y-1"><span className="break-all font-mono text-sm">{"task_ids"}</span><span className="min-w-0 break-words text-sm text-gray-500 dark:text-gray-400">optional · Sequence\[str] | None · default: <code>{"None"}</code></span></div>
</div>

**Returns**

AsyncIterator\[bytes]

For examples, see the [Python SDK guide](/sdk/runs).

<h2 id="stop">
  `client.runs.stop`
</h2>

Stop a run or selected tasks.

```python Signature theme={null}
async def stop(
    run_id: UUID,
    *,
    force: bool = False,
    task_ids: Sequence[str] | None = None,
) -> StopBenchmarkResponse
```

**Parameters**

<div className="border-b border-gray-200 py-3 dark:border-gray-800">
  <div className="flex min-w-0 flex-wrap items-baseline gap-x-2 gap-y-1"><span className="break-all font-mono text-sm">{"run_id"}</span><span className="min-w-0 break-words text-sm text-gray-500 dark:text-gray-400">required · UUID</span></div>
</div>

<div className="border-b border-gray-200 py-3 dark:border-gray-800">
  <div className="flex min-w-0 flex-wrap items-baseline gap-x-2 gap-y-1"><span className="break-all font-mono text-sm">{"force"}</span><span className="min-w-0 break-words text-sm text-gray-500 dark:text-gray-400">optional · bool · default: <code>{"False"}</code></span></div>
</div>

<div className="border-b border-gray-200 py-3 dark:border-gray-800">
  <div className="flex min-w-0 flex-wrap items-baseline gap-x-2 gap-y-1"><span className="break-all font-mono text-sm">{"task_ids"}</span><span className="min-w-0 break-words text-sm text-gray-500 dark:text-gray-400">optional · Sequence\[str] | None · default: <code>{"None"}</code></span></div>
</div>

**Returns**

<a href="/reference/sdk/models/runs#stop-benchmark-response"><code>StopBenchmarkResponse</code></a>

For examples, see the [Python SDK guide](/sdk/runs).

<h2 id="resume">
  `client.runs.resume`
</h2>

Resume unfinished work for a run.

```python Signature theme={null}
async def resume(
    run_id: UUID,
    *,
    concurrency: int | None = None,
    task_ids: Sequence[str] | None = None,
    secrets: Mapping[str, str] | None = None,
    service_headers: Mapping[str, str] | None = None,
    from_scratch: bool = False,
    benchmark_url: str | None = None,
) -> RetryOrResumeBenchmarkResponse
```

**Parameters**

<div className="border-b border-gray-200 py-3 dark:border-gray-800">
  <div className="flex min-w-0 flex-wrap items-baseline gap-x-2 gap-y-1"><span className="break-all font-mono text-sm">{"run_id"}</span><span className="min-w-0 break-words text-sm text-gray-500 dark:text-gray-400">required · UUID</span></div>
</div>

<div className="border-b border-gray-200 py-3 dark:border-gray-800">
  <div className="flex min-w-0 flex-wrap items-baseline gap-x-2 gap-y-1"><span className="break-all font-mono text-sm">{"concurrency"}</span><span className="min-w-0 break-words text-sm text-gray-500 dark:text-gray-400">optional · int | None · default: <code>{"None"}</code></span></div>
</div>

<div className="border-b border-gray-200 py-3 dark:border-gray-800">
  <div className="flex min-w-0 flex-wrap items-baseline gap-x-2 gap-y-1"><span className="break-all font-mono text-sm">{"task_ids"}</span><span className="min-w-0 break-words text-sm text-gray-500 dark:text-gray-400">optional · Sequence\[str] | None · default: <code>{"None"}</code></span></div>
</div>

<div className="border-b border-gray-200 py-3 dark:border-gray-800">
  <div className="flex min-w-0 flex-wrap items-baseline gap-x-2 gap-y-1"><span className="break-all font-mono text-sm">{"secrets"}</span><span className="min-w-0 break-words text-sm text-gray-500 dark:text-gray-400">optional · Mapping\[str, str] | None · default: <code>{"None"}</code></span></div>
</div>

<div className="border-b border-gray-200 py-3 dark:border-gray-800">
  <div className="flex min-w-0 flex-wrap items-baseline gap-x-2 gap-y-1"><span className="break-all font-mono text-sm">{"service_headers"}</span><span className="min-w-0 break-words text-sm text-gray-500 dark:text-gray-400">optional · Mapping\[str, str] | None · default: <code>{"None"}</code></span></div>
</div>

<div className="border-b border-gray-200 py-3 dark:border-gray-800">
  <div className="flex min-w-0 flex-wrap items-baseline gap-x-2 gap-y-1"><span className="break-all font-mono text-sm">{"from_scratch"}</span><span className="min-w-0 break-words text-sm text-gray-500 dark:text-gray-400">optional · bool · default: <code>{"False"}</code></span></div>
</div>

<div className="border-b border-gray-200 py-3 dark:border-gray-800">
  <div className="flex min-w-0 flex-wrap items-baseline gap-x-2 gap-y-1"><span className="break-all font-mono text-sm">{"benchmark_url"}</span><span className="min-w-0 break-words text-sm text-gray-500 dark:text-gray-400">optional · str | None · default: <code>{"None"}</code></span></div>
</div>

**Returns**

<a href="/reference/sdk/models/runs#retry-or-resume-benchmark-response"><code>RetryOrResumeBenchmarkResponse</code></a>

For examples, see the [Python SDK guide](/sdk/runs).

<h2 id="retry">
  `client.runs.retry`
</h2>

Retry failed or selected work for a run.

```python Signature theme={null}
async def retry(
    run_id: UUID,
    *,
    concurrency: int | None = None,
    task_ids: Sequence[str] | None = None,
    secrets: Mapping[str, str] | None = None,
    service_headers: Mapping[str, str] | None = None,
    from_scratch: bool = False,
    benchmark_url: str | None = None,
) -> RetryOrResumeBenchmarkResponse
```

**Parameters**

<div className="border-b border-gray-200 py-3 dark:border-gray-800">
  <div className="flex min-w-0 flex-wrap items-baseline gap-x-2 gap-y-1"><span className="break-all font-mono text-sm">{"run_id"}</span><span className="min-w-0 break-words text-sm text-gray-500 dark:text-gray-400">required · UUID</span></div>
</div>

<div className="border-b border-gray-200 py-3 dark:border-gray-800">
  <div className="flex min-w-0 flex-wrap items-baseline gap-x-2 gap-y-1"><span className="break-all font-mono text-sm">{"concurrency"}</span><span className="min-w-0 break-words text-sm text-gray-500 dark:text-gray-400">optional · int | None · default: <code>{"None"}</code></span></div>
</div>

<div className="border-b border-gray-200 py-3 dark:border-gray-800">
  <div className="flex min-w-0 flex-wrap items-baseline gap-x-2 gap-y-1"><span className="break-all font-mono text-sm">{"task_ids"}</span><span className="min-w-0 break-words text-sm text-gray-500 dark:text-gray-400">optional · Sequence\[str] | None · default: <code>{"None"}</code></span></div>
</div>

<div className="border-b border-gray-200 py-3 dark:border-gray-800">
  <div className="flex min-w-0 flex-wrap items-baseline gap-x-2 gap-y-1"><span className="break-all font-mono text-sm">{"secrets"}</span><span className="min-w-0 break-words text-sm text-gray-500 dark:text-gray-400">optional · Mapping\[str, str] | None · default: <code>{"None"}</code></span></div>
</div>

<div className="border-b border-gray-200 py-3 dark:border-gray-800">
  <div className="flex min-w-0 flex-wrap items-baseline gap-x-2 gap-y-1"><span className="break-all font-mono text-sm">{"service_headers"}</span><span className="min-w-0 break-words text-sm text-gray-500 dark:text-gray-400">optional · Mapping\[str, str] | None · default: <code>{"None"}</code></span></div>
</div>

<div className="border-b border-gray-200 py-3 dark:border-gray-800">
  <div className="flex min-w-0 flex-wrap items-baseline gap-x-2 gap-y-1"><span className="break-all font-mono text-sm">{"from_scratch"}</span><span className="min-w-0 break-words text-sm text-gray-500 dark:text-gray-400">optional · bool · default: <code>{"False"}</code></span></div>
</div>

<div className="border-b border-gray-200 py-3 dark:border-gray-800">
  <div className="flex min-w-0 flex-wrap items-baseline gap-x-2 gap-y-1"><span className="break-all font-mono text-sm">{"benchmark_url"}</span><span className="min-w-0 break-words text-sm text-gray-500 dark:text-gray-400">optional · str | None · default: <code>{"None"}</code></span></div>
</div>

**Returns**

<a href="/reference/sdk/models/runs#retry-or-resume-benchmark-response"><code>RetryOrResumeBenchmarkResponse</code></a>

For examples, see the [Python SDK guide](/sdk/runs).