Job Methods - Sutro Docs

Listing jobs

list_jobs(self)

List all jobs associated with the API key.

Returns: list: A list of job details.

Getting job status

get_job_status(self, job_id: str)

Get the status of a job by its ID.

Parameters:

job_id (str): The ID of the job to retrieve the status for.

Returns: dict: The status of the job.

Getting job results

get_job_results(self, job_id: str, include_inputs: bool = False, include_cumulative_logprobs: bool = False, with_original_df: pl.DataFrame | pd.DataFrame = None, output_column: str = 'inference_result')

Get the results of a job by its ID.

Parameters:

job_id (str): The ID of the job to retrieve the results for.
include_inputs (bool, optional): Whether to include the inputs in the results. Defaults to False.
include_cumulative_logprobs (bool, optional): Whether to include the cumulative logprobs in the results. Defaults to False.
with_original_df (Union[pl.DataFrame, pd.DataFrame], optional): Original DataFrame to join results with. Defaults to None.
output_column (str, optional): Name of the column containing results. Defaults to “inference_result”.
disable_cache (bool, optional): Whether to disable reading from or writing to the local job results cache. Defaults to False.
unpack_json (bool, optional): If the output_column is formatted as a JSON string, decides whether to unpack the top level JSON fields in the results into separate columns. Defaults to True.

Returns: Union[pl.DataFrame, pd.DataFrame]: Results as a DataFrame.

If with_original_df is provided: Returns the same type as the input DataFrame with results added as a new column
If with_original_df is None: Returns a polars DataFrame by default

The DataFrame will contain:

inputs column (if include_inputs=True). Each cell contains the input string given to the model.
The user-provided ID column when the job was submitted with id_column. This column is returned even when include_inputs=False.
inference_result column (or custom name via output_column)
cumulative_logprobs column (if include_cumulative_logprobs=True)

Example:

# Get just the results
results = sutro.get_job_results(job_id)
# Returns: pl.DataFrame with one column 'inference_result'

# Get results with inputs
results = sutro.get_job_results(job_id, include_inputs=True)
# Returns: pl.DataFrame with columns ['inputs', 'inference_result']

# Add results back to original DataFrame
df_with_results = sutro.get_job_results(job_id, with_original_df=original_df)
# Returns: Same type as original_df with 'inference_result' column added. Matches the return shape of .infer(...) when stay_attached=True.

Choosing between get_job_results() and download_job_results():

Use get_job_results() for smaller jobs — as a rule of thumb, up to the thousands of rows. One call returns a ready-to-use DataFrame: the output column is named inference_result, structured outputs are unpacked into columns, and results are cached locally. The whole result set is held in memory.
Use download_job_results() for anything larger, or when you want the results as a durable Parquet file on disk rather than a DataFrame. It streams with a progress bar and resumes interrupted downloads, but hands you the raw artifact: the output column is named after the job ID, and structured outputs stay as JSON strings.

Downloading large results

download_job_results(self, job_id: str, output_path: Optional[str] = None, include_inputs: bool = False, include_cumulative_logprobs: bool = False, resume: bool = True, expires_in_seconds: int = 3600)

Download a job’s results as a single Parquet file on local disk. This is the recommended way to retrieve results for production-scale jobs — anything beyond the thousands of rows, embedding jobs especially. For small jobs, get_job_results() is more convenient: it returns a ready DataFrame with friendly column names and unpacked structured outputs, but holds everything in memory. This method instead streams the job’s unified Parquet artifact to disk with a progress bar and returns the local path, leaving the file exactly as the server produced it. An interrupted download leaves a .part file behind. When resume is True, rerunning the call picks up where it left off using an HTTP Range request, validated against the artifact’s ETag — if the artifact changed server-side (or the ETag isn’t available), the download restarts from scratch instead of resuming.

Parameters:

job_id (str): The ID of the job to download results for.
output_path (str, optional): Where to write the Parquet file. May be a directory (the server-provided artifact filename is used) or a full file path. Defaults to the artifact filename in the current directory.
include_inputs (bool, optional): Whether to include the inputs in the results. Defaults to False.
include_cumulative_logprobs (bool, optional): Whether to include the cumulative logprobs in the results. Defaults to False.
resume (bool, optional): Whether to resume a partial download if one exists. Defaults to True.
expires_in_seconds (int, optional): TTL for the underlying presigned URLs, up to 604800 (7 days). Defaults to 3600.

Returns: str: The local path of the downloaded Parquet file. Returns None if the request fails.

The job must have succeeded before results can be downloaded — the backend returns 409 for jobs that are still running, since the results artifact is cached permanently once materialized. Use await_job_completion() first.

The Parquet file’s columns differ from get_job_results() in one important way: the output column is named after the job ID, not inference_result. The file contains:

inputs column (if include_inputs=True)
The user-provided ID column when the job was submitted with id_column. This column is included even when include_inputs=False.
An output column named after the job ID (e.g. job-76844041-b2bf-4248-9603-b7f750231b34)
cumulative_logprobs column (if include_cumulative_logprobs=True)
confidence_score column (when the model provides one)

Structured outputs are kept as raw JSON strings; nothing is unpacked into separate columns (unlike get_job_results(unpack_json=True)).

Example:

import polars as pl

local_path = sutro.download_job_results(job_id, include_inputs=True)
results_df = pl.read_parquet(local_path)  # or pl.scan_parquet to read lazily

# The output column is named after the job ID
outputs = results_df[job_id]

# Interrupted? Run the same call again and it resumes from the .part file
local_path = sutro.download_job_results(job_id, include_inputs=True)

Getting a results download URL

results_download_url(self, job_id: str, include_inputs: bool = False, include_cumulative_logprobs: bool = False, expires_in_seconds: int = 3600)

Get presigned download URLs for a job’s results artifact, without downloading anything. This is the escape hatch underneath download_job_results(): use it when you want the URLs themselves — to hand the download off to another system, fetch from a different machine, or issue partial Range reads. It wraps the results download URL endpoint; see that page for the full payload reference and raw-HTTP download patterns.

Parameters:

job_id (str): The ID of the job to retrieve results for.
include_inputs (bool, optional): Whether to include the inputs in the results. Defaults to False.
include_cumulative_logprobs (bool, optional): Whether to include the cumulative logprobs in the results. Defaults to False.
expires_in_seconds (int, optional): TTL for the returned presigned URLs, up to 604800 (7 days). Defaults to 3600.

Returns: dict: The endpoint payload, containing artifact metadata (filename, size_bytes, …) and presigned urls — urls.get for downloading (supports HTTP Range requests) and urls.head for metadata only. Returns None if the request fails.

Treat presigned URLs like credentials: anyone with the URL can download the results until it expires. Do not send your Sutro Authorization header when using them — the URL already contains the credentials.

Example:

import requests

meta = sutro.results_download_url(job_id)

# Check the artifact size without downloading
head = requests.head(meta["urls"]["head"])
print(int(head.headers["Content-Length"]))

# Hand meta["urls"]["get"] to whatever does the actual download,
# e.g. a data pipeline running on another machine

Cancelling jobs

cancel_job(self, job_id: str)

Cancel a job by its ID.

Parameters:

job_id (str): The ID of the job to cancel.

Returns: dict: The status of the job cancellation.

​Listing jobs

​Getting job status

​Getting job results

​Downloading large results

​Getting a results download URL

​Cancelling jobs

Listing jobs

Getting job status

Getting job results

Downloading large results

Getting a results download URL

Cancelling jobs