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

# Get AWS Private Connections

> Retrieve all your configured AWS S3 private connections

## Overview

This endpoint retrieves a list of all AWS S3 private connections you have configured for your Pictory account. Use this to view your existing connections, check their status, and get connection IDs for use in video creation requests.

<Note>
  You need a valid API key to use this endpoint. Get your API key from the [API Access page](https://app.pictory.ai/api-access) in your Pictory dashboard.
</Note>

***

## Use Cases

<CardGroup cols={2}>
  <Card title="View All Connections" icon="eye">
    See all your configured AWS S3 connections in one place
  </Card>

  <Card title="Get Connection IDs" icon="id-card">
    Retrieve connection IDs to use in video creation requests
  </Card>

  <Card title="Check Status" icon="check-circle">
    Verify which connections are currently enabled or disabled
  </Card>

  <Card title="Audit Configuration" icon="list-check">
    Review your AWS account IDs and regions
  </Card>
</CardGroup>

***

## API Endpoint

```http theme={null}
GET https://api.pictory.ai/pictoryapis/v1/awsconnections
```

***

## Request Parameters

### Headers

<ParamField header="Authorization" type="string" required>
  API key for authentication (starts with `pictai_`)

  ```
  Authorization: YOUR_API_KEY
  ```

  Get your API key from the [API Access page](https://app.pictory.ai/api-access) in your Pictory dashboard.
</ParamField>

***

## Response

Returns an array of AWS connection objects in the `Items` field. If no connections are configured, returns an empty array.

### Response Examples

<ResponseExample>
  ```json 200 - Success (With Connections) theme={null}
  {
    "Items": [
      {
        "connectionId": "20251217080657842fux3au9kh1p0j5s",
        "name": "TestAWSConnection",
        "description": "Test AWS Connection for Documentation",
        "awsAccountId": "123456789012",
        "awsRegion": "us-east-2",
        "type": "AWS",
        "enabled": true,
        "createdDate": "2025-12-17T08:06:56.862Z",
        "updatedDate": "2025-12-17T08:06:56.862Z",
        "version": 1
      }
    ]
  }
  ```

  ```json 200 - Success (No Connections) theme={null}
  {
    "Items": []
  }
  ```

  ```json 401 - Unauthorized theme={null}
  {
    "message": "Unauthorized"
  }
  ```
</ResponseExample>

***

## Code Examples

<Tip>
  Replace `YOUR_API_KEY` with your actual API key that starts with `pictai_`
</Tip>

<CodeGroup>
  ```bash cURL theme={null}
  # Retrieve all AWS connections
  # Replace YOUR_API_KEY with your actual API key

  curl --request GET \
    --url https://api.pictory.ai/pictoryapis/v1/awsconnections \
    --header 'Authorization: YOUR_API_KEY' \
    --header 'accept: application/json' | python -m json.tool
  ```

  ```javascript JavaScript / Node.js theme={null}
  // Replace 'YOUR_API_KEY' with your actual API key

  const getAwsConnections = async (apiKey) => {
    const response = await fetch('https://api.pictory.ai/pictoryapis/v1/awsconnections', {
      method: 'GET',
      headers: {
        'Authorization': `${apiKey}`
      }
    });

    if (!response.ok) {
      const error = await response.json();
      throw new Error(`Failed: ${error.message}`);
    }

    return await response.json();
  };

  // Usage
  try {
    const result = await getAwsConnections('YOUR_API_KEY');  // ← Replace with your API key
    console.log('Your AWS Connections:', result.Items);

    // Get the first connection ID
    if (result.Items.length > 0) {
      console.log('First Connection ID:', result.Items[0].connectionId);
    }
  } catch (error) {
    console.error('Error:', error.message);
  }
  ```

  ```python Python theme={null}
  # Replace 'YOUR_API_KEY' with your actual API key

  import requests

  def get_aws_connections(api_key):
      """Retrieve all AWS S3 connections"""
      url = "https://api.pictory.ai/pictoryapis/v1/awsconnections"

      headers = {
          "Authorization": api_key
      }

      response = requests.get(url, headers=headers)
      response.raise_for_status()

      return response.json()

  # Usage
  try:
      result = get_aws_connections("YOUR_API_KEY")  # ← Replace with your API key
      print(f"Your AWS Connections: {result['Items']}")

      # Get the first connection ID
      if len(result['Items']) > 0:
          print(f"First Connection ID: {result['Items'][0]['connectionId']}")
  except requests.exceptions.HTTPError as e:
      error = e.response.json()
      print(f"Error: {error.get('message', 'Request failed')}")
  ```

  ```php PHP theme={null}
  <?php
  // Replace 'YOUR_API_KEY' with your actual API key

  function getAwsConnections($apiKey) {
      $url = 'https://api.pictory.ai/pictoryapis/v1/awsconnections';

      $ch = curl_init($url);
      curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
      curl_setopt($ch, CURLOPT_HTTPHEADER, [
          'Authorization: ' . $apiKey
      ]);

      $response = curl_exec($ch);
      $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
      curl_close($ch);

      if ($httpCode !== 200) {
          $error = json_decode($response, true);
          throw new Exception($error['message'] ?? 'Request failed');
      }

      return json_decode($response, true);
  }

  // Usage
  try {
      $result = getAwsConnections('YOUR_API_KEY');  // ← Replace with your API key
      echo "Your AWS Connections:\n";
      print_r($result['Items']);

      // Get the first connection ID
      if (count($result['Items']) > 0) {
          echo "First Connection ID: " . $result['Items'][0]['connectionId'] . "\n";
      }
  } catch (Exception $e) {
      echo "Error: " . $e->getMessage() . "\n";
  }
  ?>
  ```

  ```go Go theme={null}
  // Replace "YOUR_API_KEY" with your actual API key

  package main

  import (
      "encoding/json"
      "fmt"
      "io"
      "net/http"
  )

  type AwsConnection struct {
      ConnectionID string `json:"connectionId"`
      Name         string `json:"name"`
      Description  string `json:"description"`
      Enabled      bool   `json:"enabled"`
      AWSAccountID string `json:"awsAccountId"`
      AWSRegion    string `json:"awsRegion"`
      Version      int    `json:"version"`
  }

  type AwsConnectionsResponse struct {
      Items []AwsConnection `json:"Items"`
  }

  func getAwsConnections(apiKey string) (*AwsConnectionsResponse, error) {
      url := "https://api.pictory.ai/pictoryapis/v1/awsconnections"

      req, err := http.NewRequest("GET", url, nil)
      if err != nil {
          return nil, err
      }

      req.Header.Set("Authorization", apiKey)

      client := &http.Client{}
      resp, err := client.Do(req)
      if err != nil {
          return nil, err
      }
      defer resp.Body.Close()

      body, err := io.ReadAll(resp.Body)
      if err != nil {
          return nil, err
      }

      if resp.StatusCode != http.StatusOK {
          return nil, fmt.Errorf("request failed (status %d): %s", resp.StatusCode, string(body))
      }

      var result AwsConnectionsResponse
      if err := json.Unmarshal(body, &result); err != nil {
          return nil, err
      }

      return &result, nil
  }

  // Usage
  func main() {
      result, err := getAwsConnections("YOUR_API_KEY")  // ← Replace with your API key
      if err != nil {
          panic(err)
      }

      fmt.Printf("Your AWS Connections: %+v\n", result.Items)

      // Get the first connection ID
      if len(result.Items) > 0 {
          fmt.Printf("First Connection ID: %s\n", result.Items[0].ConnectionID)
      }
  }
  ```
</CodeGroup>

***

## Common Use Cases

### Find Connection ID for Video Creation

When creating videos with private S3 assets, you need to provide the `awsConnectionId`. Use this endpoint to retrieve it:

```javascript theme={null}
// Get all connections and find the one you need
const result = await getAwsConnections(apiKey);
const myConnection = result.Items.find(conn => conn.name === 'PictoryPrivateVideosConnection');

if (myConnection) {
  console.log('Use this ID in video requests:', myConnection.connectionId);
}
```

### Check if Connections are Enabled

```python theme={null}
result = get_aws_connections(api_key)

for connection in result['Items']:
    status = "Active" if connection['enabled'] else "Disabled"
    print(f"{connection['name']}: {status}")
```

### List All Regions

```javascript theme={null}
const result = await getAwsConnections(apiKey);
const regions = result.Items.map(conn => conn.awsRegion);
console.log('Configured regions:', [...new Set(regions)]);
```

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Create AWS Connection" icon="plus" href="/api-reference/aws-integration/aws-private-connection">
    Set up a new AWS S3 private connection
  </Card>

  <Card title="Use in Videos" icon="video" href="/api-reference/video-storyboard/update-storyboard-elements">
    Learn how to use connection IDs in video creation
  </Card>

  <Card title="Get API Key" icon="key" href="https://app.pictory.ai/api-access">
    Access your API key from your Pictory dashboard
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/api-reference/aws-integration/aws-private-connection#troubleshooting">
    Common issues and solutions
  </Card>
</CardGroup>