> ## 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.

# Retrieving Results

> Retrieve the results of a batch inference job by its job_id

<Warning>Using the API directly is not recommended for most users. Instead, we recommend using the [Python
SDK](/python-sdk/setup).</Warning>

Download the complete results of a batch inference job. Results can be downloaded in multiple formats optimized for different use cases.

## Path Parameters

<ParamField path="job_id" type="string" required>
  The job\_id returned when you submitted the batch inference job
</ParamField>

## Query Parameters

<ParamField query="result_format" type="enum" required>
  The format to download results in:

  * `csv` - CSV file (zipped for compression)
  * `parquet` - Parquet file
  * `json` - JSON object
</ParamField>

<ParamField query="include_inputs" type="boolean" default="false">
  Whether to include the input prompts in the results
</ParamField>

<ParamField query="include_cumulative_logprobs" type="boolean" default="false">
  Whether to include the cumulative log probabilities in the results
</ParamField>

## Headers

<ParamField header="Authorization" type="string" required>
  Your Sutro API key using Key authentication scheme.

  Format: `Key YOUR_API_KEY`

  Example: `Authorization: Key sk_abc123...`
</ParamField>

## Response

Returns a downloadable file in the requested format.

### Parquet

* Returns a single Parquet file
* Recommended for large datasets

### CSV

* Returns a ZIP file containing a CSV
* File is compressed for efficient transfer
* Column names: `inputs`, `{job_id}` `outputs`, `cumulative_logprobs` (if requested)

### JSON

* Returns a JSON object
* Best for smaller datasets

## Structured Outputs

When using structured outputs (by providing a `json_schema` when creating the job), the outputs will be JSON strings that conform to your specified schema.

### Standard Models

For non-reasoning models, the output will be a JSON string following your schema:

```json theme={null}
{
  "outputs": [
    "{\"name\": \"John Doe\", \"age\": 30, \"email\": \"john@example.com\"}",
    "{\"name\": \"Jane Smith\", \"age\": 25, \"email\": \"jane@example.com\"}"
  ]
}
```

### Reasoning Models

For reasoning models (like o1), the output includes both the structured content and the reasoning process:

```json theme={null}
{
  "outputs": [
    "{\"content\": {\"name\": \"John Doe\", \"age\": 30}, \"reasoning_content\": \"First, I identified the name from the text...\"}",
    "{\"content\": {\"name\": \"Jane Smith\", \"age\": 25}, \"reasoning_content\": \"I analyzed the passage and extracted...\"}"
  ]
}
```

The output structure for reasoning models:

* `content`: The structured output following your JSON schema (can be a text string or JSON string containing an object matching your schema)
* `reasoning_content`: The model's step-by-step reasoning process (string)

Currently, when using structured outputs or reasoning models, one will need to run `json.loads` or similar on each output JSON, ie `json.loads(outputs[0])` to transform from a string to a `dict` (or equivalent in other languages).

<ResponseExample>
  ```json JSON Format theme={null}
  {
      "outputs": [
          "The capital of France is Paris.",
          "Quantum computing uses quantum mechanics principles to process information in ways that classical computers cannot..."
      ],
      "inputs": [
          "What is the capital of France?",
          "Explain quantum computing in simple terms"
      ],
      "cumulative_logprobs": [-0.5234, -1.2456]
  }
  ```

  ```csv CSV Format (inside zip) theme={null}
  inputs,job-abc123,cumulative_logprobs
  "What is the capital of France?","The capital of France is Paris.",-0.5234
  "Explain quantum computing in simple terms","Quantum computing uses quantum mechanics principles to process
  information in ways that classical computers cannot...",-1.2456
  ```

  ```text Parquet Format theme={null}
  Same structure as CSV, but with preserved data types:
  - inputs (string)
  - job-abc123 (string or JSON string)
  - cumulative_logprobs (float64)

  Binary format optimized for data analysis tools (pandas, polars, duckdb)
  ```
</ResponseExample>

## Code Examples

<CodeGroup>
  ```python Python - CSV Download theme={null}
  import requests

  response = requests.get(
      'https://api.sutro.sh/jobs/job_12345/results',
      headers={
          'Authorization': 'Key YOUR_SUTRO_API_KEY'
      },
      params={
          'result_format': 'csv',
          'include_inputs': True,
          'include_cumulative_logprobs': False
      }
  )

  # Save the zip file
  with open('results.zip', 'wb') as f:
      f.write(response.content)

  # Extract and read with pandas
  import zipfile
  import pandas as pd

  with zipfile.ZipFile('results.zip') as z:
      csv_filename = z.namelist()[0]
      with z.open(csv_filename) as csv_file:
      df = pd.read_csv(csv_file)
      print(df.head())
  ```

  ```python Python - Parquet Download theme={null}
  import requests
  import polars as pl

  response = requests.get(
      'https://api.sutro.sh/jobs/job_12345/results',
      headers={
          'Authorization': 'Key YOUR_SUTRO_API_KEY'
      },
      params={
          'result_format': 'parquet',
          'include_inputs': True
      }
  )

  # Save and read with pandas
  with open('results.parquet', 'wb') as f:
      f.write(response.content)

  df = pl.read_parquet('results.parquet')
  print(df.head())
  ```

  ```python Python - JSON Download theme={null}
  import requests

  response = requests.get(
      'https://api.sutro.sh/jobs/job_12345/results',
      headers={
          'Authorization': 'Key YOUR_SUTRO_API_KEY'
      },
      params={
          'result_format': 'json',
          'include_inputs': True,
          'include_cumulative_logprobs': False
      }
  )

  result = response.json()

  # Access outputs and inputs
  for i, (input_text, output_text) in enumerate(zip(result['inputs'], result['outputs'])):
      print(f"Input {i + 1}: {input_text}")
      print(f"Output {i + 1}: {output_text}")
      print("---")
  ```

  ```curl cURL - CSV Download theme={null}
  curl -X GET "https://api.sutro.sh/jobs/job_12345/results?result_format=csv&include_inputs=true" \
  -H "Authorization: Key YOUR_SUTRO_API_KEY" \
  -o results.zip
  ```

  ```curl cURL - JSON Download theme={null}
  curl -X GET "https://api.sutro.sh/jobs/job_12345/results?result_format=json&include_inputs=true" \
  -H "Authorization: Key YOUR_SUTRO_API_KEY"
  ```
</CodeGroup>

## Notes

* Results can only be retrieved for jobs that have completed successfully
* The order of results matches the order of the original inputs
* CSV format: outputs are in a column named after the job\_id
* Parquet format uses zstd compression internally
* For very large datasets (>100MB), Parquet is recommended
* CSV files are automatically zipped to reduce download size