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

# Jobs and results

> Monitor jobs and retrieve, download, list, or cancel results.

# Jobs and results

The examples use the shared client:

```python theme={null}
import sutro as so
```

## Inspect and control jobs

### `list_jobs`

```text theme={null}
list_jobs() -> list[dict] | None
```

Returns all jobs for the current API key as `list[dict]`, or `None` if the
request fails.

### `get_job_status`

```text theme={null}
get_job_status(job_id: str) -> str | None
```

Returns the status string, or `None` if the request fails.

### `attach`

```text theme={null}
attach(job_id: str) -> None
```

Streams progress for an active job and returns `None`. It exits immediately if
the job is missing or already terminal.

### `cancel_job`

```text theme={null}
cancel_job(job_id: str) -> dict | None
```

Requests asynchronous cancellation and returns the API response dictionary, or
`None` if the request fails.

### `get_quotas`

```text theme={null}
get_quotas() -> list[dict] | None
```

Returns row and token quota records by priority as `list[dict]`, or `None` if
the request fails.

## Wait for completion

```text theme={null}
await_job_completion(
    job_id: str,
    timeout: int | None = 7200,
    obtain_results: bool = True,
    output_column: str = "inference_result",
    is_cost_estimate: bool = False,
) -> polars.DataFrame | None
```

Polls every five seconds. It returns a Polars DataFrame only after `SUCCEEDED`
when `obtain_results=True`; otherwise it returns `None`. `output_column` names
the result column. `is_cost_estimate` is accepted for compatibility but does not
change the current polling behavior. Check `get_job_status()` to distinguish a
failure, cancellation, timeout, or intentionally omitted results.

## Materialize manageable results

```text theme={null}
get_job_results(
    job_id: str,
    include_inputs: bool = False,
    include_cumulative_logprobs: bool = False,
    with_original_df: polars.DataFrame | pandas.DataFrame | None = None,
    output_column: str = "inference_result",
    disable_cache: bool = False,
    unpack_json: bool = True,
) -> polars.DataFrame | pandas.DataFrame | None
```

Results are Polars by default and match the type of `with_original_df` when
provided. User ID columns and `confidence_score` are preserved. Structured JSON
is unpacked into columns by default; set `unpack_json=False` to retain the raw
output. Results are cached under `~/.sutro/job-results` unless disabled.

## Get a download URL

```text theme={null}
results_download_url(
    job_id: str,
    include_inputs: bool = False,
    include_cumulative_logprobs: bool = False,
    expires_in_seconds: int = 3600,
) -> dict | None
```

Returns a dictionary containing `artifact` metadata and presigned `urls.get`
and `urls.head`, or `None` if the request fails. The job must be `SUCCEEDED`.
URLs may live for 1–604800 seconds, are temporary credentials, and must be used
without the Sutro authorization header.

## Download large results

```text theme={null}
download_job_results(
    job_id: str,
    output_path: str | None = None,
    include_inputs: bool = False,
    include_cumulative_logprobs: bool = False,
    resume: bool = True,
    expires_in_seconds: int = 3600,
) -> str | None
```

Returns the local Parquet path, or `None` on failure. `output_path` may be a
directory or complete filename; by default it uses the artifact filename in the
current directory. Interrupted downloads resume from a `.part` file when
`resume=True` and the artifact ETag still matches. Otherwise the download
restarts.