Skip to main content

Your First Complete Sync

This tutorial builds on Getting Started by diving deeper into the sync process. You'll learn how to handle all five Vimeo URL types, choose the right sync mode for your use case, and interpret detailed sync results.

By the end of this tutorial, you'll understand:

  • How to sync each of the five Vimeo URL types
  • When to use Full vs Incremental sync modes
  • What happens during each phase of the sync process
  • How to interpret detailed sync results and metrics
  • What to do when videos don't have transcripts

This tutorial takes approximately 15-20 minutes to complete.

Prerequisites​

Before starting this tutorial, you should have:

Completed the Getting Started Tutorial - If you haven't already, complete Getting Started first. That tutorial covers the basics of the dashboard interface and your first simple import.

Access to the Dashboard - Navigate to https://vimeo.trustedgpt.io and verify you see the "Connected" status indicator in the top-right corner.

Test URLs Ready - You'll need several different Vimeo URL types to test. Use these provided test URLs:

User Profile: https://vimeo.com/user230805735
User Albums: https://vimeo.com/user230805735/albums
User Videos: https://vimeo.com/user230805735/videos
User Collections: https://vimeo.com/user230805735/collections
Showcase: https://vimeo.com/showcase/11708791

These test URLs are provided by CustomGPT.ai for testing purposes and contain a mix of videos with and without transcripts.

Understanding the Five Vimeo URL Types​

The Vimeo Connector supports five distinct URL types. Each type represents a different way of organizing videos on Vimeo, and understanding these differences helps you choose the right URL for your import needs.

1. User Profile URLs​

Format: https://vimeo.com/user{userid}

What It Imports: All public videos uploaded by this Vimeo user, across all albums, showcases, and collections. This is the most comprehensive import for a specific user.

Example: https://vimeo.com/user230805735

When to Use: When you want everything from a specific Vimeo account. This is useful when you're importing content from your own Vimeo account or a partner's account where you have permission to use all their videos.

Behind the Scenes: The connector calls Vimeo's /users/{userid}/videos API endpoint, which returns all videos owned by this user. It automatically handles pagination if the user has hundreds or thousands of videos.

2. User Albums URLs​

Format: https://vimeo.com/user{userid}/albums

What It Imports: All albums owned by this user, along with all videos in those albums. An album is Vimeo's way of grouping related videos together (similar to a playlist).

Example: https://vimeo.com/user230805735/albums

When to Use: When you want organized collections from a user account. Albums typically have curated themes (like "Product Tutorials", "Customer Testimonials", etc.), so importing albums gives you pre-organized content.

Behind the Scenes: The connector makes two types of API calls: first, it fetches all albums owned by the user via /users/{userid}/albums, then for each album, it fetches the videos inside via /albums/{albumid}/videos.

3. User Videos URLs​

Format: https://vimeo.com/user{userid}/videos

What It Imports: All videos uploaded by this user, but as a flat list without any album or collection organization. This is similar to User Profile URLs but explicitly focuses on the videos themselves.

Example: https://vimeo.com/user230805735/videos

When to Use: When you want all videos from a user but don't care about how they're organized into albums or showcases. This is the simplest import for getting "all videos from this account."

Behind the Scenes: Calls /users/{userid}/videos endpoint, identical to User Profile URLs. The two URL types exist because Vimeo users structure their URLs differently, but the connector treats them the same.

4. User Collections URLs​

Format: https://vimeo.com/user{userid}/collections

What It Imports: All collections owned by this user and the videos within them. Collections are similar to albums but can include videos from other Vimeo users (not just videos you own).

Example: https://vimeo.com/user230805735/collections

When to Use: When you want curated collections that might include third-party videos. This is useful for importing "Best Of" collections or topic-based collections that aggregate videos from multiple sources.

Behind the Scenes: The connector calls /users/{userid}/collections to get all collections, then for each collection, calls /collections/{collectionid}/videos to get the videos. Collections can contain videos from multiple users, so transcript availability may vary widely.

5. Showcase URLs​

Format: https://vimeo.com/showcase/{showcaseid}

What It Imports: All videos in a specific showcase. A showcase is Vimeo's premium feature for creating branded, curated collections of videos with custom layouts.

Example: https://vimeo.com/showcase/11708791

When to Use: When you have a specific showcase URL and want to import just that one collection. This is the most targeted import—you're saying "I want exactly these videos from this showcase."

Behind the Scenes: The connector calls /albums/{showcaseid} (showcases are a type of album in Vimeo's API) and then /albums/{showcaseid}/videos to get the videos. Showcases are often curated for specific purposes, so transcript availability depends on how the showcase owner prepared their videos.

Sync Modes Explained​

The Vimeo Connector offers three sync modes. Understanding when to use each mode helps you balance thoroughness with speed.

How It Works: Auto mode detects whether you've imported this URL before:

  • First time import: Automatically performs a Full Sync
  • Repeat import: Automatically performs an Incremental Sync

Advantages:

  • You don't have to remember whether you've imported this URL before
  • Optimizes for speed on repeat imports without risking missed content
  • Best default choice for 90% of use cases

When to Use: Always use Auto mode unless you have a specific reason to override it.

Example Scenario: You import a showcase today (Auto mode does Full Sync). Next week, you import the same showcase again (Auto mode does Incremental Sync, only fetching new or updated videos added in the past week).

Full Sync Mode​

How It Works: Fetches all videos from the Vimeo URL, even if you've imported this URL before. Compares each video against any existing data and marks videos as "Added" (new) or "Updated" (changed) or "Unchanged" (identical).

Advantages:

  • Guarantees you have 100% of the current content
  • Useful for recovering from failed imports
  • Good for periodic "refresh everything" operations

Disadvantages:

  • Slower than Incremental Sync for repeat imports
  • Makes more API calls to Vimeo
  • Still respects rate limits, so very large collections can take time

When to Use:

  • You suspect a previous import missed content
  • You want to force a complete refresh of all data
  • It's been months since your last import and you want to ensure nothing was missed

Example Scenario: You imported a user's video library 6 months ago. Since then, they may have updated video descriptions or added new transcripts. Running a Full Sync ensures you get all current data, including any updates to existing videos.

Incremental Sync Mode​

How It Works: Only fetches videos that are new or have been modified since your last import. Uses checksum comparison—each video's content (title, description, transcript) generates a hash, and only videos with changed hashes are re-downloaded.

Advantages:

  • Fastest mode for repeat imports
  • Minimizes API calls to Vimeo
  • Ideal for frequent, scheduled imports (e.g., nightly sync jobs)

Disadvantages:

  • Fails if you've never imported this URL before (no previous state to compare against)
  • Relies on accurate checksums—if previous import was corrupted, incremental won't fix it

When to Use:

  • You're setting up automated, frequent syncs (daily/weekly)
  • You know you've successfully imported this URL recently
  • You want to minimize API usage and maximize speed

Example Scenario: You import a showcase every night at midnight using Incremental Sync. Each night, the connector only fetches videos that were added or updated that day, taking 30 seconds instead of 10 minutes for a Full Sync.

Step-by-Step: Your First Full Sync​

Let's walk through a detailed sync using the Showcase test URL. This will demonstrate all phases of the sync process.

Phase 1: Initiate the Sync​

  1. Open the dashboard at https://vimeo.trustedgpt.io
  2. Paste the showcase URL into the input field: 
    https://vimeo.com/showcase/11708791
  3. Set Sync Mode to "Full Sync" (for this tutorial, we want to see the full process)
  4. Click "Import Collection"

What Happens Immediately:

  • The dashboard sends a POST request to /api/v1/sync with your URL and mode
  • The backend creates a job with a unique ID (e.g., sync_a1b2c3d4)
  • The job is added to the processing queue
  • Your browser starts polling for job status every 1.5 seconds

Phase 2: Discovery​

Status Badge Shows: "Starting..." (blue)

What's Happening:

  • The connector validates your Vimeo URL format
  • It extracts the showcase ID from the URL (11708791)
  • It calls Vimeo's API to fetch showcase metadata: /albums/11708791
  • This API call returns the showcase title, description, and total video count

Duration: 2-5 seconds

Why This Matters: The total video count discovered in this phase determines the denominator for the progress bar. If the showcase has 100 videos, the progress bar will count from 0% to 100% as it processes all 100 videos.

Phase 3: Video Fetching​

Status Badge Shows: "Running" (blue)

Progress Bar Appears: "Processing 0 of 100 videos (0%)"

What's Happening:

  • The connector calls /albums/11708791/videos to get the list of videos
  • This returns video IDs, titles, descriptions, durations, thumbnail URLs, upload dates, and other metadata
  • If there are more than 100 videos, Vimeo's API paginates the results—the connector automatically follows pagination links to fetch all pages

Duration: 5-15 seconds for small showcases, 1-2 minutes for large showcases (hundreds of videos)

Why This Matters: This is the first batch of API calls. The connector respects Vimeo's rate limit (600 calls per 10 minutes by default, or 3600 calls per 10 minutes with Token Pool enabled). Large showcases may trigger rate limiting, causing the process to slow down briefly.

Phase 4: Transcript Fetching​

Progress Bar Updates: "Processing 1 of 100 videos (1%)"

Current Video Shows: The title of the first video being processed

What's Happening:

  • For each video, the connector calls /videos/{videoid}/texttracks to check for native transcripts
  • If a transcript exists, the API returns the transcript URL (usually a .vtt or .srt file)
  • The connector downloads the transcript file and parses it:
    • VTT files: Strips timing codes and formatting, extracting plain text
    • SRT files: Strips numbering and timing codes, extracting plain text
  • If no transcript exists, the API returns an empty array—the connector records "no transcript available" and moves on

Duration: 1-3 seconds per video (depends on transcript file size and Vimeo API response time)

Why This Matters: This is the most time-consuming phase. A showcase with 100 videos might take 2-5 minutes to fetch all transcripts. The connector processes videos sequentially to avoid overwhelming Vimeo's API.

What You'll See: The progress bar increments from 1% → 2% → 3% as each video is processed. The "Current Video" display changes every few seconds, showing you exactly which video is being worked on.

Phase 5: Checksum Comparison​

Behind the Scenes (Not Visible in UI):

For each video, the connector generates a checksum (hash) of the video's content:

checksum = hash(title + description + transcript_text + duration + upload_date)

If this URL was imported before, the connector compares the new checksum against the stored checksum:

  • Checksum matches: Video is "Unchanged"
  • Checksum differs: Video is "Updated" (content changed)
  • No previous checksum exists: Video is "Added" (new video)

If this is your first import (or you selected Full Sync), all videos will be marked as "Added" because there are no previous checksums to compare against.

Why This Matters: Checksum comparison enables Incremental Sync mode. On repeat imports, the connector can quickly identify which videos need re-processing without re-downloading everything.

Phase 6: Storage​

Behind the Scenes (Not Visible in UI):

For each video marked as "Added" or "Updated", the connector stores the data:

  • Metadata JSON: Saved to /data/videos/{videoid}.json (or database in production)
  • Transcript Text: Saved to /data/transcripts/{videoid}.txt
  • Checksum: Saved to /data/checksums/{videoid}.hash

Videos marked as "Unchanged" are skipped—their existing stored data is retained.

Phase 7: Completion​

Status Badge Shows: "Completed" (green)

Progress Bar Disappears: Replaced by Results Summary

Results Summary Shows:

Added: 5
Updated: 0
Deleted: 0
Unchanged: 0

Completed in 87 seconds

What These Numbers Mean:

  • Added: 5 — 5 videos were newly imported (this was your first import, so all videos are new)
  • Updated: 0 — No videos had content changes (only relevant on repeat imports)
  • Deleted: 0 — No videos were removed from the showcase (only relevant on repeat imports)
  • Unchanged: 0 — No videos were identical to previous imports (only relevant on repeat imports)

Step-by-Step: Your First Incremental Sync​

Now let's see how Incremental Sync works by re-importing the same showcase.

Prepare for Incremental Sync​

Before running an Incremental Sync, you need to have previously imported this URL at least once. If you just completed the Full Sync exercise above, you're ready to test Incremental Sync on the same URL.

Run the Incremental Sync​

  1. In the dashboard, paste the same showcase URL you just imported: 
    https://vimeo.com/showcase/11708791
  2. Set Sync Mode to "Incremental Sync"
  3. Click "Import Collection"

Observe the Differences​

Discovery Phase (Same as Full Sync):

  • The connector fetches showcase metadata
  • Total video count is determined (should be the same as before)

Video Fetching Phase (Same as Full Sync):

  • All video metadata is fetched from Vimeo
  • This step still happens even in Incremental mode—the connector needs current metadata to compare checksums

Checksum Comparison Phase (Different from Full Sync):

  • For each video, the connector generates a checksum of the current content
  • It loads the stored checksum from the previous Full Sync
  • It compares:
    • If checksums match → Mark as "Unchanged" and skip transcript fetching
    • If checksums differ → Mark as "Updated" and re-fetch transcript
    • If no stored checksum → Mark as "Added" and fetch transcript

Transcript Fetching Phase (Much Faster):

  • Only videos marked as "Added" or "Updated" have their transcripts fetched
  • Videos marked as "Unchanged" are skipped entirely—their existing transcript data is retained

Results Summary:

Added: 0
Updated: 0
Deleted: 0
Unchanged: 5

Completed in 12 seconds

What These Numbers Mean:

  • Added: 0 — No new videos were added to the showcase since your last import
  • Updated: 0 — No existing videos had their content changed
  • Unchanged: 5 — All 5 videos are identical to the previous import
  • Completed in 12 seconds — Much faster than the 87 seconds of the Full Sync because transcript fetching was skipped for unchanged videos

Understanding Detailed Results​

Let's explore what each result metric means and when you might see different values.

Added Videos​

What It Means: Videos that exist in the Vimeo collection now but did not exist in your previous import.

When You'll See This:

  • First import: All videos are marked as "Added"
  • Repeat import after content was added: If the Vimeo user added new videos to the showcase/album since your last import, those new videos show as "Added"

Example Scenario: You imported a showcase yesterday with 10 videos. Today, the Vimeo user added 3 more videos to the showcase. Running an Incremental Sync shows "Added: 3".

Updated Videos​

What It Means: Videos that existed in your previous import but have had their content changed.

What Counts as an Update:

  • Title changed
  • Description changed
  • Transcript added or modified
  • Tags changed
  • Duration changed (e.g., video was re-uploaded with edits)

When You'll See This:

  • A Vimeo user edited a video's title or description
  • A transcript was added to a video that previously had none
  • A video was re-uploaded with a different version

Example Scenario: You imported a showcase last week. Since then, the video owner added transcripts to 2 videos that previously had none. Running a Full or Incremental Sync shows "Updated: 2".

Deleted Videos​

What It Means: Videos that existed in your previous import but no longer exist in the Vimeo collection.

When You'll See This:

  • A Vimeo user removed a video from the showcase/album
  • A video was deleted entirely from Vimeo
  • A video's privacy settings changed (e.g., set to private), making it invisible to the API

What Happens to Deleted Videos:

  • The connector does not automatically delete stored data for deleted videos
  • It marks them as "deleted" in metadata but retains the files
  • This is a safety feature—you can manually review deleted videos before removing their data

Example Scenario: You imported an album with 20 videos. The Vimeo user removed 2 outdated videos from the album. Running a Full or Incremental Sync shows "Deleted: 2".

Unchanged Videos​

What It Means: Videos that existed in your previous import and have not changed since then.

When You'll See This:

  • Only on Incremental or Full syncs (not on first imports)
  • The video's content (title, description, transcript, etc.) is identical to the previous import

Why This Matters: High "Unchanged" counts on Incremental Syncs indicate the sync was efficient—most videos were skipped, saving time and API calls.

Example Scenario: You import a showcase every week. On week 2, 50 of 100 videos are unchanged, 2 are updated, and 3 are added. Your results show "Added: 3, Updated: 2, Deleted: 0, Unchanged: 50" and the sync completes in 90 seconds instead of 5 minutes.

Handling Videos Without Transcripts​

Not all videos will have native transcripts. This is normal and expected. Here's how to interpret and handle this situation.

Why Videos Might Not Have Transcripts​

Transcript Upload is Optional: Vimeo does not require video owners to upload transcripts. Many Vimeo users simply don't provide them.

Auto-Generated Captions Are Not Accessible: Some Vimeo plans include auto-generated captions, but these are only available through the Vimeo player UI—they're not exposed via the API. The connector can only access manually uploaded transcripts.

Third-Party Videos in Collections: If you're importing a collection (as opposed to an album), the collection might include videos from other users. Those users might not have uploaded transcripts.

How the Connector Handles Missing Transcripts​

When the connector encounters a video without a transcript:

  1. It still imports the video metadata (title, description, duration, thumbnail, tags, etc.)
  2. It records "transcript: null" in the JSON metadata
  3. It logs a warning (visible in backend logs, not in the UI)
  4. It continues processing remaining videos (missing transcripts do not cause failures)

Checking Transcript Availability Before Import​

If transcripts are critical for your use case, you can manually check before importing:

Method 1: Check on Vimeo.com

  1. Open the video on Vimeo in a browser
  2. Start playing the video
  3. Look for the CC (closed captions) button in the player controls
  4. Click CC—if captions appear, a native transcript exists

Method 2: Use Vimeo's API Explorer

  1. Go to Vimeo API Explorer
  2. Call GET /videos/{videoid}/texttracks
  3. If the response array is non-empty, transcripts exist

What to Do When Transcripts Are Missing​

Option 1: Request Transcripts from Video Owner If you control the Vimeo account or have contact with the video owner, ask them to upload transcripts manually. Once uploaded, re-run a Full or Incremental Sync to fetch the new transcripts.

Option 2: Import Metadata Only Even without transcripts, video metadata (title, description, tags) can still be useful for search and organization in CustomGPT.ai's knowledge base. The connector will import this metadata regardless of transcript availability.

Option 3: Generate Transcripts Externally You can download video audio using third-party tools, generate transcripts with services like OpenAI Whisper or Rev.com, and then manually upload them to Vimeo. Once uploaded, the connector will fetch them on the next sync.

Note: The connector does not generate transcripts from audio. It only fetches native Vimeo transcripts.

Troubleshooting Common Issues​

Issue: Sync Fails with "Invalid Vimeo URL"​

Cause: The URL format is incorrect or the resource doesn't exist on Vimeo.

Solution:

  • Double-check the URL matches one of the five supported formats
  • Copy the URL directly from Vimeo (don't type it manually)
  • Verify the resource exists by opening the URL in a browser

Issue: Sync Fails with "Authentication Error"​

Cause: The Vimeo API token is expired, invalid, or missing required scopes.

Solution:

  • This typically indicates a backend configuration issue
  • Contact your CustomGPT.ai administrator to verify the API token is configured correctly
  • Required Vimeo API scopes: public, private (to access video metadata and transcripts)

Issue: Sync Is Very Slow​

Cause: Large collections (hundreds of videos) combined with rate limiting.

Solution:

  • Enable Token Pool: If you're importing large libraries, set up the Token Pool feature for 6x faster imports. See How to Set Up Token Pool.
  • Use Incremental Sync: On repeat imports, Incremental Sync skips unchanged videos, dramatically reducing time.
  • Be Patient: A showcase with 500 videos might take 30-60 minutes on first import. This is normal due to Vimeo's API rate limits (600 calls per 10 minutes).

Issue: Progress Bar Is Stuck​

Cause: Network issues, backend server overload, or Vimeo API downtime.

Solution:

  • Refresh the dashboard page and check the "Recent Jobs" sidebar—the job might still be running even if progress updates stopped
  • Wait 5-10 minutes—the backend might be rate-limited by Vimeo and paused briefly
  • Check Vimeo's status page: https://status.vimeo.com

Issue: Incremental Sync Fails with "No Previous State"​

Cause: You tried to run an Incremental Sync on a URL you've never imported before.

Solution:

  • Switch to "Full Sync" or "Auto" mode for first-time imports
  • Incremental Sync only works on URLs that have been previously imported

Next Steps​

Congratulations! You now understand the full sync process, all five URL types, and how to choose the right sync mode.

Continue Learning:

Explore the Dashboard - Learn about all UI components, real-time updates, and job management. See Exploring the Dashboard.

Monitor Long-Running Syncs - Techniques for tracking progress on large imports (hundreds of videos). See How to Monitor Sync Progress.

View Sync Results in Detail - Learn how to access the JSON metadata and transcript files generated by syncs. See How to View Sync Results.

Set Up Token Pool for 6x Speed - Enable the Token Pool feature to increase capacity from 600 to 3600 API calls per 10 minutes. See How to Set Up Token Pool.

Understand the Architecture - Dive deep into how the connector works under the hood. See How It Works.

You're now ready to confidently import any Vimeo content into CustomGPT.ai's knowledge base!