Skip to main content

Connect Vimeo

Tasks call Vimeo through qbash.integrations.vimeo. The connector reads an account's videos, folders, showcases, comments, captions and chapters, and on Enterprise plans its analytics. It makes no changes to the account.

After you connect Vimeo, you can add its tools to a qbash MCP server for ChatGPT, Claude and other MCP clients, or call it from a Python task. The Vimeo MCP server page lists what the connector can do.

There are two ways to connect:

  • Sign in with Vimeo connects in one step. qbash asks Vimeo for the Public, Private and Stats scopes.
  • Personal access token uses a token you generate on your own Vimeo app. Enterprise accounts on a custom vimeo.work subdomain need this option.

Sign in with Vimeo​

  1. Open Connectors, then Vimeo, and click Connect.
  2. Keep Sign in with Vimeo selected, enter a credential name and click Connect Vimeo.
  3. Vimeo opens in a new window. Sign in to the account the tasks should read and click Allow. Leave every listed permission ticked. Without Private the connector cannot read your videos, and without Stats it cannot read analytics.
  4. In the task editor, open Resources → Integrations and select this credential. See Connect resources.

The token that sign-in creates has no expiry date. Vimeo still removes it after a long time unused, and the credential then shows Needs Re-auth until you reconnect it from the Connectors page.

Create a personal access token​

  1. Sign in to Vimeo and verify your email address. Vimeo will not create an app for an unverified account. On a team account, sign in as the team owner, because Vimeo only lets the owner create apps.
  2. Open developer.vimeo.com/apps and click Create an app. Enter a name and description, answer No to whether people besides you will access the app, and accept the terms.
  3. On the app's page, find Generate an access token. Choose Authenticated (you) and tick Public, Private and Stats. qbash needs Private to read your own videos, and Stats for analytics.
  4. Click Generate and copy the token. Vimeo shows it once.

Add the token in qbash​

  1. Open Connectors, then Vimeo, and click Connect.
  2. Choose Personal access token, enter a credential name and paste the token.
  3. Leave API Host blank unless your Enterprise account uses a custom subdomain such as qbash.vimeo.work. In that case enter api.qbash.vimeo.work, because Vimeo refuses calls to api.vimeo.com for those accounts.
  4. Click Add Credential. qbash checks the token with Vimeo before saving it and refuses a token without the Private scope or one generated as Unauthenticated.
  5. In the task editor, open Resources → Integrations and select this credential. See Connect resources.

When editing the credential, leave the token blank to keep the saved one. Renaming the credential keeps its authentication status.

Vimeo does not set an expiry on personal access tokens. It removes a token that goes unused for a long time, and the credential then shows Needs Re-auth. Generate a new token and paste it into the credential.

Read videos from a task​

page = qbash.integrations.vimeo.list_videos(sort="plays", direction="desc", limit=10)
for video in page["videos"]:
    print(video["name"], video.get("plays"), video["link"])

list_videos filters by text (query), tag (filter_tag) and kind (filter), and sorts by date, plays, likes, duration and more. Each call reads one page of up to 100 videos. Pass next_cursor back as cursor until it is None. Keys whose value Vimeo left empty are missing from each video, so read optional ones with .get().

get_video, list_comments, list_text_tracks, get_transcript and list_chapters take a video ID or the video's URL. list_folders and list_showcases return the IDs that list_folder_videos and list_showcase_videos need.

Get a transcript​

transcript = qbash.integrations.vimeo.get_transcript(video_id="https://vimeo.com/76979871", language="en")
print(transcript["text"][:500])

get_transcript downloads a caption or subtitle track and returns its text. Pass include_segments=True for start and end times in seconds. A video needs a text track first: upload a caption file, or wait for Vimeo's automatic captions to finish. Only the video's owner can read its tracks.

Read a team's content​

A team member's credential reads the team's videos, folders and showcases when the call passes the team owner's numeric user ID:

page = qbash.integrations.vimeo.list_folders(user_id="12345678")

To find the ID, call get_video on a team video and read the number at the end of owner_uri.

Analytics on Enterprise plans​

get_analytics returns views, impressions, finishes and watch time for a date range, grouped by video, country, device or another dimension. Vimeo serves it only on Enterprise plans, and only to an app that Vimeo Support has enabled for analytics:

  • With Sign in with Vimeo, the token comes from qbash's Vimeo app, so Vimeo has to enable analytics for that app. Vimeo has not enabled analytics for qbash's app yet, so use a personal access token for analytics for now.
  • With a personal access token, ask Vimeo Support to enable API analytics for your own app, giving its name and client ID, and generate the token with the Stats scope.

Without that, the call returns an error that names what is missing.

report = qbash.integrations.vimeo.get_analytics(
    dimension="video",
    start_date="2026-09-01",
    end_date="2026-09-30",
    sort="views",
    direction="desc",
    limit=20,
)
for row in report["rows"]:
    print(row)

Dates are UTC days and end_date is inclusive. Add time_interval="week" to split each row by week.

Seed a test account​

A free Vimeo account covers everything except analytics. Upload a short video, add a caption file to it from the video's settings, put it in a folder and a showcase, and leave a comment on it.

Limits​

  • Vimeo limits requests per token per minute by plan. Every method except get_analytics asks only for the fields it returns, which Vimeo counts at half cost, so their limits are 50 on Free, 250 on Starter, 500 on Standard, 1,500 on Advanced and 5,000 on Enterprise. Over the limit, calls fail with a 429 until the minute resets.
  • plays is the lifetime play count Vimeo shows on the video.
  • Caption download links in list_text_tracks expire. Read a fresh link each run instead of storing one.
  • Vimeo sometimes turns off public search, and search_videos then returns a 503.
  • Durations are in seconds, and times are ISO 8601 in UTC.
Last updated on