Getting Started with Vimeo Connector

In this tutorial, you'll import your first Vimeo collection and watch the process happen in real-time. By the end of these 5 minutes, you'll understand how the connector works and be ready to import your entire video library.

Prefer video? Watch the walkthrough

See the complete import workflow in action. This 10-minute demo shows every step from pasting a URL to viewing results.

What's covered in the video:

• Landing page with 5 URL type explanations (0:00)
• Complete showcase sync workflow (2:15)
• Real-time progress updates (4:30)
• Results summary and job history (7:45)
• Error handling demonstration (9:00)

Video recorded by QA tester Hamza during demo rehearsal

What You'll Learn

This hands-on tutorial teaches you how to:

• Navigate to the Vimeo Connector dashboard
• Paste a Vimeo URL and start an import
• Monitor progress as videos are processed
• Interpret the results showing what was imported
• Access imported transcript content

No prior experience with APIs, Docker, or command-line tools is required. Everything happens through a web interface that you can use from any modern browser.

Prerequisites

Before you begin, you need:

Access to the Dashboard - Navigate to https://vimeo.trustedgpt.io in your web browser. The dashboard works in Chrome, Firefox, Safari, and Edge (current versions). Make sure JavaScript is enabled—the real-time progress updates require it.

A Vimeo URL to Test - You can use any public Vimeo URL. If you don't have one handy, use this demo showcase provided for testing:

https://vimeo.com/showcase/11708791

This showcase contains multiple videos with transcripts, making it perfect for seeing the connector in action.

5 Minutes of Time - The actual import takes 1-2 minutes for a small collection, but budget 5 minutes total to read through explanations and explore the interface.

Step 1: Open the Dashboard

Navigate to https://vimeo.trustedgpt.io in your browser. You'll see the Vimeo Connector dashboard, which is divided into two main areas:

Left Side: Import Controls - This is where you'll paste Vimeo URLs and start imports. The left side contains:

• A large input field for pasting URLs
• A dropdown to select sync mode (Auto, Full, or Incremental)
• An "Import Collection" button to start the process

Right Side: Job History - This sidebar shows all recent import jobs, whether they're running, completed, or failed. Each job displays:

• The Vimeo URL you imported
• Current status (Queued, Running, Completed, Failed, Cancelled)
• How many videos were processed
• How long the import took

At the top of the page, you'll see a connection status indicator showing a green dot with "Connected" text. This confirms the dashboard can communicate with the backend API. If you see "Backend not reachable" in red, the system is currently unavailable—try refreshing the page or check back in a few minutes.

The header also displays the Vimeo Connector logo (a blue Vimeo icon) alongside the title "Vimeo Data Connector" with subtitle "CustomGPT.ai Integration". This confirms you're on the correct application.

Step 2: Paste a Vimeo URL

Click inside the "Vimeo URL" input field in the left panel. This field accepts any of five Vimeo URL types:

• Showcases - Collections of curated videos
• User Profiles - All videos from a Vimeo user
• Albums - Organized video albums
• Collections - User-created collections
• Single Videos - Individual video URLs

For this tutorial, paste the demo showcase URL:

https://vimeo.com/showcase/11708791

As soon as you paste the URL, the input field validates it. If the URL is valid Vimeo format, the field border remains neutral. If you paste an invalid URL (like a YouTube link or malformed Vimeo URL), the field will show a validation error.

What's Happening Behind the Scenes: The system hasn't contacted Vimeo yet. URL validation happens entirely in your browser, checking that the format matches one of the five supported Vimeo URL patterns. The actual import doesn't start until you click the button in the next step.

Step 3: Select Sync Mode

Below the URL input, you'll see a "Sync Mode" dropdown with three options:

Auto (Recommended) - The default and smartest choice. Auto mode detects whether this is your first time importing this URL or a repeat import:

• First import: Performs a full sync, fetching all videos and transcripts
• Repeat import: Performs an incremental sync, only fetching new or updated videos

Choose Auto unless you have a specific reason to override this behavior.

Full Sync - Always fetches all videos, even if you've imported this URL before. Use this if you suspect previous imports missed content or if you want to force a complete re-import. Full syncs take longer but guarantee nothing is missed.

Incremental Sync - Only fetches videos that are new or have been updated since your last import. This is faster for repeat imports but will fail if you've never imported this URL before (because there's no previous state to compare against).

For this tutorial, leave the mode set to "Auto". Since this is your first import of the demo showcase, Auto mode will automatically choose Full Sync behind the scenes.

Step 4: Start the Import

Click the large "Import Collection" button at the bottom of the left panel. The button is styled in Vimeo blue (#1ab7ea) and displays a small upload icon to the left of the text.

Immediate Response: The button instantly changes to show a loading spinner, preventing you from accidentally clicking it twice. The left panel slides down to reveal a new Progress Card that takes over the interface.

The Progress Card displays:

• Job Status Badge at the top center showing "Starting..." in blue
• Progress Bar (initially hidden until the job begins processing)
• Current Video Name showing which video is being processed
• Cancel Button in the top-right corner, allowing you to stop the import if needed

What's Happening Behind the Scenes: Your browser sent a POST request to the API endpoint /api/v1/sync with your Vimeo URL and sync mode. The backend created a job with a unique ID (like sync_a1b2c3d4) and added it to the processing queue. The job worker (a background process) picks up your job and begins contacting Vimeo's API.

Step 5: Watch Real-Time Progress

Within 2-3 seconds, the status badge changes from "Starting..." to "Running" and the progress bar appears. This is when the actual import begins.

The Progress Bar displays three pieces of information simultaneously:

Percentage Complete - Shown on the right side (e.g., "45%"). This percentage represents how many videos have been processed out of the total discovered. If the showcase contains 100 videos and 45 have been processed, you'll see 45%.

Processed Count - Shown on the left side (e.g., "Processing 45 of 100 videos"). This gives you the exact numbers behind the percentage.

Visual Progress - The progress bar itself fills from left to right with a gradient from Vimeo blue to CustomGPT purple. The fill animation is smooth, updating every 1.5 seconds as new progress data arrives from the backend.

The Current Video Display appears below the progress bar, showing:

• The video title currently being processed
• A truncated version if the title is very long (hover to see the full title)

For example, you might see:

Current: "Introduction to Product Features - Q3 2024 Update"

This tells you exactly which video the connector is working on right now. The current video changes every few seconds as processing moves through the collection.

Live Updates: The dashboard polls the backend API every 1.5 seconds, asking "What's the status of job sync_a1b2c3d4?" The backend responds with current progress, and the UI updates instantly. This creates the illusion of real-time progress without needing WebSocket connections or server-push technology.

What's Happening Behind the Scenes: The job worker is making multiple API calls to Vimeo:

1. Fetch showcase metadata - Getting the list of videos in this showcase
2. Fetch video details - For each video, retrieving title, description, duration, thumbnail URL, and other metadata
3. Check for transcripts - Calling Vimeo's text track API to see if a native transcript exists
4. Download transcripts - If a transcript is available, downloading the VTT or SRT file and parsing it into plain text

All of this happens server-side. Your browser just displays the results.

Step 6: Review the Results

After 1-2 minutes (depending on collection size), the status badge changes to "Completed" in green, and the progress bar disappears. In its place, you'll see a Results Summary displaying four key metrics:

Added: 5 - The number of videos that were newly imported. These are videos the system has never seen before from this URL.

Updated: 0 - The number of videos that already existed but had changes (updated description, new transcript, etc.). Since this is your first import, you'll typically see 0 here.

Deleted: 0 - The number of videos that were in a previous import but no longer exist in the Vimeo collection. Again, first imports show 0.

Unchanged: 0 - Videos that already existed and had no changes. First imports show 0 since everything is new.

Below these metrics, you'll see:

Completed in 87 seconds

This tells you the total duration from when you clicked "Import Collection" to when processing finished. Small showcases (5-10 videos) typically take 30-60 seconds. Large showcases (50+ videos) can take 5-10 minutes.

What These Numbers Mean: In our demo showcase example, "Added: 5" means the connector successfully imported 5 videos. Each video now has:

• Metadata stored as JSON (title, description, duration, tags, upload date)
• Transcript text (if the video had a native Vimeo transcript)
• Thumbnail URL
• Source URL back to the original Vimeo video

This data is now ready to be ingested into CustomGPT.ai's knowledge base, making the video content searchable through AI-powered conversations.

Step 7: View Job History

Look at the right sidebar labeled "Recent Jobs". Your completed import now appears at the top of the list. Each job in this sidebar shows:

Job Card Elements:

• Vimeo URL (truncated with "..." if very long - hover to see the full URL in a tooltip)
• Status Badge (green "Completed" badge with checkmark icon)
• Results Summary showing "5 added, 0 updated, 0 deleted"
• Timestamp showing when the import started (e.g., "2 minutes ago")

You can click on any job card to re-open its details in the main progress area. This is useful for reviewing the results of older imports or checking what happened if an import failed.

The job history persists in your browser's session. If you refresh the page, recent jobs remain visible (they're fetched from the backend API, not just stored in browser memory). However, if you close your browser and come back hours later, very old jobs may no longer appear in the list—the sidebar typically shows the 10 most recent jobs.

Step 8: Understanding Transcript Coverage

An important detail: Not all imported videos will have transcripts. The Vimeo Connector only fetches native Vimeo transcripts—transcripts that the video owner uploaded to Vimeo manually. The connector does not generate transcripts from audio using speech-to-text services.

When you import a collection, you might see:

• 5 videos imported, 3 with transcripts - This means 5 videos had their metadata imported, but only 3 of those videos had native transcripts available on Vimeo.

This is completely normal and expected. Many Vimeo users don't upload transcripts to their videos. The connector will still import the video metadata (title, description, tags, etc.) even if no transcript exists, but the transcript field will be empty.

Why This Matters: If you're importing videos specifically for their transcript content (to make them searchable in CustomGPT.ai), you'll want to choose Vimeo collections where you know transcripts exist. Check a few videos manually on Vimeo—if you see closed captions available in the Vimeo player, those videos have native transcripts that the connector can import.

What You Just Accomplished

Congratulations! You've successfully completed your first import with the Vimeo Connector. Here's what happened:

You Initiated an Import - By pasting a Vimeo URL and clicking "Import Collection", you triggered an automated process that contacted Vimeo's API on your behalf.

The Connector Fetched Metadata - For each video in the showcase, the connector retrieved title, description, duration, thumbnail, tags, upload date, and other metadata. This metadata is now stored as structured JSON data.

Transcripts Were Downloaded - For videos that had native Vimeo transcripts, the connector downloaded and parsed those transcripts into plain text format, preserving timestamp information.

Progress Was Tracked - You watched the import happen in real-time, seeing exactly which video was being processed at each moment. The progress bar gave you a clear sense of how much work remained.

Results Were Reported - At the end, you saw a clear summary of what was imported: 5 new videos with their transcripts and metadata, ready to be ingested into CustomGPT.ai's knowledge base.

Common Questions

Q: Can I import multiple collections at once?

A: Not simultaneously from the same browser tab. If you paste a new URL while another import is running, the new import will be queued and start after the current one finishes. However, you can open the dashboard in multiple browser tabs and run concurrent imports from different tabs. The backend handles multiple jobs in parallel using a single background worker with a queue system.

Q: What happens if I close my browser while an import is running?

A: The import continues running on the server. Closing your browser doesn't cancel the job—it just stops you from seeing progress updates. When you reopen the dashboard, you can click on the job in the "Recent Jobs" sidebar to see its current status or final results.

Q: Can I cancel an import once it's started?

A: Yes. Click the "Cancel" button in the top-right corner of the Progress Card while the import is running. The backend will stop processing new videos and mark the job as "Cancelled". Videos that were already processed before you clicked Cancel will still be saved—only remaining videos are skipped.

Q: What if the import fails?

A: If an import fails (due to network issues, invalid API tokens, or Vimeo API errors), the status badge changes to "Failed" in red, and an error message appears explaining what went wrong. Common failure reasons include:

• Invalid Vimeo URL - The URL format was valid but the resource doesn't exist on Vimeo
• Authentication Error - The Vimeo API token is expired or invalid
• Rate Limit Exceeded - Too many requests were made to Vimeo's API in a short time (the connector has built-in rate limiting to prevent this, but it can still happen under heavy load)

If you see a failure, check the error message for details and try again. Most failures are transient (temporary network issues) and succeed on retry.

Q: How do I know if videos have transcripts before importing?

A: The best way is to manually check a few videos on Vimeo.com. Open the video in a browser and look for the CC (closed captions) button in the Vimeo player. If the CC button is available and displays captions, that video has a native transcript the connector can import. If there's no CC button or it says "No captions available", the video has no native transcript.

Next Steps

Now that you've completed your first import, you're ready to explore more features:

Import Different URL Types - Try importing a user profile, album, collection, or single video URL. See How to Sync Different URL Types for guides on each type.

Monitor Larger Imports - Import a showcase with 50+ videos to see how the connector handles larger workloads. Learn techniques for monitoring long-running imports in How to Monitor Sync Progress.

View Imported Content - Learn how to access the JSON data and transcripts that were imported. See How to View Sync Results for details on the output format.

Enable 6x Capacity (Advanced) - If you need to import large video libraries (hundreds of videos), learn how to set up the token pool feature for 6x faster imports. See How to Set Up Token Pool.

Understand the Architecture - Want to know how the connector works under the hood? Read How It Works for a deep-dive into the system architecture.

Deploy Your Own Instance - If you need to run the connector in your own infrastructure, see the deployment instructions in the GitHub repository.

You're now ready to import your entire Vimeo library and make it searchable through CustomGPT.ai!