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

> Retrieve all configured Vimeo connections

## Overview

Retrieve a paginated list of all Vimeo connections associated with your account. The response includes connection metadata while excluding sensitive credentials (client secrets and access tokens) for security.

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

***

## API Endpoint

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

***

## Request Parameters

### Headers

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

  ```
  Authorization: YOUR_API_KEY
  ```
</ParamField>

### Query Parameters

<ParamField query="nextPageKey" type="string">
  Base64-encoded pagination token for retrieving the next page of results. Returned in the previous response when more results are available.

  **Example:** `"eyJsYXN0RXZhbHVhdGVkS2V5Ijp7fX0="`
</ParamField>

***

## Response

Returns a paginated array of Vimeo connection objects in the `Items` field. Each connection includes `connectionId`, `name`, `description`, `clientIdentifier`, `type`, `enabled` status, timestamps, and `version` number. If more results are available, a `nextPageKey` is included for pagination. For security, sensitive credentials (`clientSecret` and `accessToken`) are never returned in API responses.

### Response Examples

<ResponseExample>
  ```json 200 - Success theme={null}
  {
    "Items": [
      {
        "connectionId": "20251004004125558w7qnfweid5ilsos",
        "name": "Pictory API",
        "clientIdentifier": "925dbcbdc591d6463c5e289a3825e1a3e0602b97",
        "type": "VIMEO",
        "enabled": true,
        "createdDate": "2025-10-04T00:41:24.597Z",
        "updatedDate": "2025-10-04T00:41:24.597Z",
        "version": 1
      },
      {
        "connectionId": "20251222155613307xv0nodhitf9cd0f",
        "name": "Test Vimeo Connection",
        "description": "Testing Vimeo connection via API",
        "clientIdentifier": "test_client_id_123",
        "type": "VIMEO",
        "enabled": true,
        "createdDate": "2025-12-22T15:56:12.309Z",
        "updatedDate": "2025-12-22T15:56:12.309Z",
        "version": 1
      }
    ]
  }
  ```

  ```json 401 - Unauthorized theme={null}
  {
    "message": "Unauthorized"
  }
  ```

  ```json 500 - Internal Server Error theme={null}
  {
    "error": {
      "code": "INTERNAL_ERROR",
      "message": "An unexpected error occurred"
    }
  }
  ```
</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 Vimeo connections
  # Replace YOUR_API_KEY with your actual API key

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

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

  const getVimeoConnections = async (apiKey, nextPageKey = null) => {
    const url = new URL('https://api.pictory.ai/pictoryapis/v1/vimeo-connections');

    // Add pagination parameter if provided
    if (nextPageKey) {
      url.searchParams.append('nextPageKey', nextPageKey);
    }

    const response = await fetch(url, {
      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 getVimeoConnections('YOUR_API_KEY');
    console.log('Vimeo Connections:', result.Items);
    console.log('Total Connections:', result.Items.length);

    // Handle pagination if nextPageKey exists
    if (result.nextPageKey) {
      console.log('More results available. Use nextPageKey for next page.');
      const nextPage = await getVimeoConnections('YOUR_API_KEY', result.nextPageKey);
      console.log('Next Page:', nextPage.Items);
    }
  } catch (error) {
    console.error('Error:', error.message);
  }
  ```

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

  import requests

  def get_vimeo_connections(api_key, next_page_key=None):
      """Retrieve all Vimeo connections"""
      url = "https://api.pictory.ai/pictoryapis/v1/vimeo-connections"

      headers = {
          "Authorization": api_key
      }

      # Add pagination parameter if provided
      params = {}
      if next_page_key:
          params['nextPageKey'] = next_page_key

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

      return response.json()

  # Usage
  try:
      result = get_vimeo_connections("YOUR_API_KEY")
      print(f"Vimeo Connections: {result['Items']}")
      print(f"Total Connections: {len(result['Items'])}")

      # Handle pagination if nextPageKey exists
      if 'nextPageKey' in result:
          print("More results available. Use nextPageKey for next page.")
          next_page = get_vimeo_connections("YOUR_API_KEY", result['nextPageKey'])
          print(f"Next Page: {next_page['Items']}")
  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 getVimeoConnections($apiKey, $nextPageKey = null) {
      $url = 'https://api.pictory.ai/pictoryapis/v1/vimeo-connections';

      // Add pagination parameter if provided
      if ($nextPageKey) {
          $url .= '?nextPageKey=' . urlencode($nextPageKey);
      }

      $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 = getVimeoConnections('YOUR_API_KEY');
      echo "Vimeo Connections:\n";
      print_r($result['Items']);
      echo "Total Connections: " . count($result['Items']) . "\n";

      // Handle pagination if nextPageKey exists
      if (isset($result['nextPageKey'])) {
          echo "More results available. Use nextPageKey for next page.\n";
          $nextPage = getVimeoConnections('YOUR_API_KEY', $result['nextPageKey']);
          echo "Next Page:\n";
          print_r($nextPage['Items']);
      }
  } 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"
      "net/url"
  )

  type VimeoConnection struct {
      ConnectionID     string `json:"connectionId"`
      Name             string `json:"name"`
      Description      string `json:"description"`
      ClientIdentifier string `json:"clientIdentifier"`
      Type             string `json:"type"`
      Enabled          bool   `json:"enabled"`
      CreatedDate      string `json:"createdDate"`
      UpdatedDate      string `json:"updatedDate"`
      Version          int    `json:"version"`
  }

  type VimeoConnectionsResponse struct {
      Items       []VimeoConnection `json:"Items"`
      NextPageKey string            `json:"nextPageKey,omitempty"`
  }

  func getVimeoConnections(apiKey string, nextPageKey string) (*VimeoConnectionsResponse, error) {
      baseURL := "https://api.pictory.ai/pictoryapis/v1/vimeo-connections"

      // Add pagination parameter if provided
      if nextPageKey != "" {
          params := url.Values{}
          params.Add("nextPageKey", nextPageKey)
          baseURL = baseURL + "?" + params.Encode()
      }

      req, err := http.NewRequest("GET", baseURL, 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 VimeoConnectionsResponse
      if err := json.Unmarshal(body, &result); err != nil {
          return nil, err
      }

      return &result, nil
  }

  // Usage
  func main() {
      result, err := getVimeoConnections("YOUR_API_KEY", "")
      if err != nil {
          panic(err)
      }

      fmt.Printf("Vimeo Connections: %+v\n", result.Items)
      fmt.Printf("Total Connections: %d\n", len(result.Items))

      // Handle pagination if nextPageKey exists
      if result.NextPageKey != "" {
          fmt.Println("More results available. Use nextPageKey for next page.")
          nextPage, err := getVimeoConnections("YOUR_API_KEY", result.NextPageKey)
          if err != nil {
              panic(err)
          }
          fmt.Printf("Next Page: %+v\n", nextPage.Items)
      }
  }
  ```
</CodeGroup>

***

## Pagination

This endpoint supports pagination for handling large result sets:

1. **First Request:** Make initial request without the `nextPageKey` parameter
2. **Check for More Results:** If the response includes `nextPageKey`, additional results are available
3. **Subsequent Requests:** Include the `nextPageKey` value as a query parameter to retrieve the next page

**Example with pagination:**

```http theme={null}
GET https://api.pictory.ai/pictoryapis/v1/vimeo-connections?nextPageKey=eyJsYXN0RXZhbHVhdGVkS2V5Ijp7fX0=
```

***

## Error Handling

<AccordionGroup>
  <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="Empty Results" icon="list">
    **Cause:** No Vimeo connections exist in your account

    **Solution:**

    * This is expected if you have not created any Vimeo connections yet
    * Use the [Create Vimeo Connection](/api-reference/vimeo-integration/create-vimeo-connection) endpoint to add your first connection
    * Verify you are using the correct API key for your account
  </Accordion>

  <Accordion title="Pagination Issues" icon="arrows-rotate">
    **Cause:** Getting the same results when using `nextPageKey` or pagination not working

    **Solution:**

    * Ensure you are passing the `nextPageKey` value exactly as returned (Base64-encoded)
    * Do not modify or decode the `nextPageKey` value before sending it
    * If no `nextPageKey` is returned in the response, you have reached the end of results
    * The `nextPageKey` is only valid for the current result set
  </Accordion>
</AccordionGroup>