> ## 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 Connection by ID

> Retrieve details of a specific AWS S3 private connection

## Overview

This endpoint retrieves detailed information about a specific AWS S3 private connection using its unique connection ID. Use this to verify connection settings, check status, or retrieve configuration details for a particular connection.

<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="Verify Connection" icon="check-circle">
    Check if a specific connection exists and is properly configured
  </Card>

  <Card title="Get Connection Details" icon="info-circle">
    Retrieve AWS account ID, region, and other configuration details
  </Card>

  <Card title="Check Status" icon="toggle-on">
    Verify if a connection is currently enabled or disabled
  </Card>

  <Card title="Audit Configuration" icon="clipboard-list">
    Review connection settings for compliance or troubleshooting
  </Card>
</CardGroup>

***

## API Endpoint

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

***

## Request Parameters

### Path Parameters

<ParamField path="connectionid" type="string" required>
  The unique identifier of the AWS connection you want to retrieve. This is the `connectionId` value returned when you created the connection or from the list connections endpoint.

  ```
  Example: 20251217080657842fux3au9kh1p0j5s
  ```
</ParamField>

### 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 the AWS connection object with all configuration details including connection ID, AWS account information, and connection status.

### Response Examples

<ResponseExample>
  ```json 200 - Success theme={null}
  {
    "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 401 - Unauthorized theme={null}
  {
    "message": "Unauthorized"
  }
  ```

  ```json 404 - Not Found theme={null}
  {
    "message": "Connection not found"
  }
  ```
</ResponseExample>

***

## Code Examples

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

  Replace `YOUR_CONNECTION_ID` with the actual connection ID you want to retrieve
</Tip>

<CodeGroup>
  ```bash cURL theme={null}
  # Retrieve a specific AWS connection by ID
  # Replace YOUR_API_KEY with your actual API key
  # Replace YOUR_CONNECTION_ID with your connection ID

  curl --request GET \
    --url https://api.pictory.ai/pictoryapis/v1/awsconnections/YOUR_CONNECTION_ID \
    --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
  // Replace 'YOUR_CONNECTION_ID' with your connection ID

  const getAwsConnectionById = async (apiKey, connectionId) => {
    const response = await fetch(`https://api.pictory.ai/pictoryapis/v1/awsconnections/${connectionId}`, {
      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 connectionId = 'YOUR_CONNECTION_ID';  // ← Replace with your connection ID
    const result = await getAwsConnectionById('YOUR_API_KEY', connectionId);  // ← Replace with your API key
    console.log('Connection Details:', result);
    console.log('Connection Name:', result.name);
    console.log('AWS Region:', result.awsRegion);
    console.log('Enabled:', result.enabled);
  } catch (error) {
    console.error('Error:', error.message);
  }
  ```

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

  import requests

  def get_aws_connection_by_id(api_key, connection_id):
      """Retrieve a specific AWS S3 connection by ID"""
      url = f"https://api.pictory.ai/pictoryapis/v1/awsconnections/{connection_id}"

      headers = {
          "Authorization": api_key
      }

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

      return response.json()

  # Usage
  try:
      connection_id = "YOUR_CONNECTION_ID"  # ← Replace with your connection ID
      result = get_aws_connection_by_id("YOUR_API_KEY", connection_id)  # ← Replace with your API key
      print(f"Connection Details: {result}")
      print(f"Connection Name: {result['name']}")
      print(f"AWS Region: {result['awsRegion']}")
      print(f"Enabled: {result['enabled']}")
  except requests.exceptions.HTTPError as e:
      if e.response.status_code == 404:
          print("Error: Connection not found")
      else:
          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
  // Replace 'YOUR_CONNECTION_ID' with your connection ID

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

      $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 === 404) {
          throw new Exception('Connection not found');
      }

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

      return json_decode($response, true);
  }

  // Usage
  try {
      $connectionId = 'YOUR_CONNECTION_ID';  // ← Replace with your connection ID
      $result = getAwsConnectionById('YOUR_API_KEY', $connectionId);  // ← Replace with your API key
      echo "Connection Details:\n";
      print_r($result);
      echo "Connection Name: " . $result['name'] . "\n";
      echo "AWS Region: " . $result['awsRegion'] . "\n";
      echo "Enabled: " . ($result['enabled'] ? 'Yes' : 'No') . "\n";
  } catch (Exception $e) {
      echo "Error: " . $e->getMessage() . "\n";
  }
  ?>
  ```

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

  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"`
      Type         string `json:"type"`
      CreatedDate  string `json:"createdDate"`
      UpdatedDate  string `json:"updatedDate"`
      Version      int    `json:"version"`
  }

  func getAwsConnectionById(apiKey, connectionId string) (*AwsConnection, error) {
      url := fmt.Sprintf("https://api.pictory.ai/pictoryapis/v1/awsconnections/%s", connectionId)

      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.StatusNotFound {
          return nil, fmt.Errorf("connection not found")
      }

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

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

      return &result, nil
  }

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

      fmt.Printf("Connection Details: %+v\n", result)
      fmt.Printf("Connection Name: %s\n", result.Name)
      fmt.Printf("AWS Region: %s\n", result.AWSRegion)
      fmt.Printf("Enabled: %v\n", result.Enabled)
  }
  ```
</CodeGroup>

***

## Common Use Cases

### Verify Connection Before Using in Video Creation

Before creating a video with private S3 assets, verify the connection is still active:

```javascript theme={null}
// Check if connection exists and is enabled
const connection = await getAwsConnectionById(apiKey, connectionId);

if (connection.enabled) {
  console.log('Connection is active and ready to use');
  // Proceed with video creation
} else {
  console.log('Connection is disabled. Enable it before creating videos.');
}
```

### Get Connection Configuration Details

```python theme={null}
# Retrieve connection details for troubleshooting
connection = get_aws_connection_by_id(api_key, connection_id)

print(f"AWS Account ID: {connection['awsAccountId']}")
print(f"AWS Region: {connection['awsRegion']}")
print(f"Created: {connection['createdDate']}")
print(f"Last Updated: {connection['updatedDate']}")
```

### Check Connection Status

```javascript theme={null}
// Check if a specific connection is enabled
const connection = await getAwsConnectionById(apiKey, connectionId);
const status = connection.enabled ? 'Active' : 'Disabled';
console.log(`Connection "${connection.name}" is ${status}`);
```

***

## Error Handling

<AccordionGroup>
  <Accordion title="404 Not Found" icon="circle-xmark">
    **Cause:** The connection ID does not exist or has been deleted

    **Solution:**

    * Verify the connection ID is correct
    * Use the [Get AWS Connections](/api-reference/aws-integration/get-aws-connections) endpoint to list all available connections
    * Check if the connection was deleted
  </Accordion>

  <Accordion title="401 Unauthorized" icon="lock">
    **Cause:** Invalid or missing API key

    **Solution:**

    * Verify your API key is correct and starts with `pictai_`
    * Check the `Authorization` header is properly formatted: `YOUR_API_KEY`
    * Ensure your API key hasn't expired
    * Get a new API key from the [API Access page](https://app.pictory.ai/api-access)
  </Accordion>

  <Accordion title="403 Forbidden" icon="ban">
    **Cause:** You do not have permission to access this connection

    **Solution:**

    * Verify the connection belongs to your account
    * Check that your API key has the necessary permissions
    * Contact support if you believe you should have access
  </Accordion>
</AccordionGroup>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="List All Connections" icon="list" href="/api-reference/aws-integration/get-aws-connections">
    Retrieve all your AWS S3 private connections
  </Card>

  <Card title="Create Connection" icon="plus" href="/api-reference/aws-integration/aws-private-connection">
    Set up a new AWS S3 private connection
  </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="Use in Videos" icon="video" href="/api-reference/video-storyboard/update-storyboard-elements">
    Learn how to use connection IDs in video creation
  </Card>
</CardGroup>