Skip to main content
GET
https://api.pictory.ai
/
pictoryapis
/
v1
/
awsconnections
/
{connectionid}
Get AWS Connection by ID
curl --request GET \
  --url https://api.pictory.ai/pictoryapis/v1/awsconnections/{connectionid} \
  --header 'Authorization: <authorization>'
{
  "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
}

​
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.
You need a valid API key to use this endpoint. Get your API key from the API Access page in your Pictory dashboard.

​
Use Cases

Verify Connection

Check if a specific connection exists and is properly configured

Get Connection Details

Retrieve AWS account ID, region, and other configuration details

Check Status

Verify if a connection is currently enabled or disabled

Audit Configuration

Review connection settings for compliance or troubleshooting

​
API Endpoint

GET https://api.pictory.ai/pictoryapis/v1/awsconnections/{connectionid}

​
Request Parameters

​
Path Parameters

​
connectionid
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

​
Headers

​
Authorization
string
required
API key for authentication (starts with pictai_)
Authorization: YOUR_API_KEY
Get your API key from the API Access page in your Pictory dashboard.

​
Response

Returns the AWS connection object with all configuration details including connection ID, AWS account information, and connection status.

​
Response Examples

{
  "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
}

​
Code Examples

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

​
Common Use Cases

​
Verify Connection Before Using in Video Creation

Before creating a video with private S3 assets, verify the connection is still active: 
// 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

# 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

// 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

Cause: The connection ID does not exist or has been deletedSolution:
  • Verify the connection ID is correct
  • Use the Get AWS Connections endpoint to list all available connections
  • Check if the connection was deleted
Cause: Invalid or missing API keySolution:
  • 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
Cause: You don’t have permission to access this connectionSolution:
  • 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

​
Next Steps

List All Connections

Retrieve all your AWS S3 private connections

Create Connection

Set up a new AWS S3 private connection

Get API Key

Access your API key from your Pictory dashboard

Use in Videos

Learn how to use connection IDs in video creation