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

# Downloading a File

> Download a file from a dataset

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

Download a file from a dataset.

## Usage Notes

* You can only download one file at a time via the API. You must make multiple requests to download multiple files. The Python SDK supports downloading multiple files at once.
* The file will be returned as bytes. You will need to decode the bytes and save them to a file.
* The dataset stores files in the order they were uploaded. You can view the ordering of files using the `list-dataset-files` endpoint.

## Request Body

<ParamField body="dataset_id" type="string" required>
  The ID of the dataset to download the file from
</ParamField>

<ParamField body="file_name" type="string" required>
  The name of the file to download
</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_live_abc123...`
</ParamField>

## Response

If successful, returns the file as bytes. Otherwise, returns a JSON object containing an error message.

<ResponseExample>
  ```json Error Response theme={null}
  {
    "error": "File not found in dataset"
  }
  ```
</ResponseExample>

## Code Examples

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

  response = requests.post(
      'https://api.sutro.sh/download-from-dataset',
      headers={
          'Authorization': 'Key YOUR_SUTRO_API_KEY',
          'Content-Type': 'application/json'
      },
      json={
          'dataset_id': 'dataset_12345',
          'file_name': 'data.parquet'
      }
  )

  # Check if the response is successful and contains file data
  if response.headers.get('content-type') == 'application/octet-stream':
      # Save the file bytes to disk
      with open('downloaded_data.parquet', 'wb') as f:
          f.write(response.content)
      print("File downloaded successfully")
  else:
      # Handle error response
      error_info = response.json()
      print(f"Download failed: {error_info.get('error', 'Unknown error')}")
  ```

  ```javascript Node.js theme={null}
  const fs = require('fs');

  const response = await fetch('https://api.sutro.sh/download-from-dataset', {
    method: 'POST',
    headers: {
      'Authorization': 'Key YOUR_SUTRO_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      dataset_id: 'dataset_12345',
      file_name: 'data.parquet'
    })
  });

  // Check if the response contains file data
  if (response.headers.get('content-type') === 'application/octet-stream') {
    const buffer = await response.arrayBuffer();
    fs.writeFileSync('downloaded_data.parquet', Buffer.from(buffer));
    console.log('File downloaded successfully');
  } else {
    const errorInfo = await response.json();
    console.log(`Download failed: ${errorInfo.error || 'Unknown error'}`);
  }
  ```

  ```curl cURL theme={null}
  curl -X POST https://api.sutro.sh/download-from-dataset \
    -H "Authorization: Key YOUR_SUTRO_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "dataset_id": "dataset_12345",
      "file_name": "data.parquet"
    }' \
    --output downloaded_data.parquet
  ```
</CodeGroup>

## Response Handling

The API returns different content types based on the result:

* **Successful Download**: `Content-Type: application/octet-stream` with file bytes in the response body
* **Error**: `Content-Type: application/json` with error details

Always check the `Content-Type` header to determine how to handle the response.

## Important Considerations

* **Single File Limit**: API supports one file per request (use Python SDK for batch downloads)
* **Binary Data**: Files are returned as raw bytes that need to be saved to disk
* **File Ordering**: Use the `list-dataset-files` endpoint to see available files and their order
* **Error Handling**: Check response headers to distinguish between file data and error messages