Jobs and results

The examples use the shared client:

import sutro as so

Inspect and control jobs

`list_jobs`

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`

get_job_status(job_id: str) -> str | None

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

`attach`

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`

cancel_job(job_id: str) -> dict | None

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

`get_quotas`

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

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

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

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

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.

Product

MCP

Python SDK

API

Jobs and results

Jobs and results

Inspect and control jobs

`list_jobs`

`get_job_status`

`attach`

`cancel_job`

`get_quotas`

Wait for completion

Materialize manageable results

Get a download URL

Download large results

​Jobs and results

​Inspect and control jobs

​list_jobs

​get_job_status

​attach

​cancel_job

​get_quotas

​Wait for completion

​Materialize manageable results

​Get a download URL

​Download large results

Jobs and results

Inspect and control jobs

`list_jobs`

`get_job_status`

`attach`

`cancel_job`

`get_quotas`

Wait for completion

Materialize manageable results

Get a download URL

Download large results