# vimeo.channel_videos

**stable** **Advanced**

Videos in a Vimeo channel (latest page).

`GET /v1/vimeo/channel_videos`

## What you get

A list of Vimeo results in Onekey's unified shape, in `data` (an array). An empty array is a normal, successful answer and is charged like any other; a source that reports "nothing found" as an error returns a free `404 not_found` instead.

## What it costs

- **Advanced · 5 credits** for a fresh fetch, charged only when it succeeds.
- **Free when served from cache (0.2 credit for a cached response over 100 KB).**
- **Free** if the request is invalid (never charged) or the source fails or reports not found (refunded).

## Parameters

| Name | Type | Required | Default | What it is | Constraints |
| --- | --- | --- | --- | --- | --- |
| `channel` | string | yes | (required) | Vimeo channel slug | max 60 chars; must match `[a-z0-9_\-]{1,60}`; trimmed, lowercased |

## Request

```bash
curl "https://api.onekey.dev/v1/vimeo/channel_videos?channel=staffpicks" \
  -H "x-api-key: YOUR_API_KEY"
```

```python
import requests

res = requests.get(
    "https://api.onekey.dev/v1/vimeo/channel_videos",
    params={"channel": "staffpicks"},
    headers={"x-api-key": "YOUR_API_KEY"},
)
body = res.json()

if body["success"]:
    print(body["data"])
else:
    print(body["error"]["code"], body["error"]["message"])
```

```javascript
const params = new URLSearchParams({ channel: "staffpicks" });
const res = await fetch(`https://api.onekey.dev/v1/vimeo/channel_videos?${params}`, {
  headers: { "x-api-key": "YOUR_API_KEY" },
});
const body = await res.json();

if (body.success) console.log(body.data);
else console.error(body.error.code, body.error.message);
```

## Recorded response

A real Vimeo response, recorded and returned in Onekey's shape. Fields the platform does not provide are `null`.

```json
{
  "success": true,
  "data": [
    {
      "content": {
        "id": "1229308303",
        "title": "Yaya",
        "text": "Yaya is a young woman with Down syndrome who is tired of being ignored and infantilized by everyone around her. While working at her uncle’s grocery store, Yaya befriends Genesis, a rebellious teenager who proposes getting a tattoo together, challenging her to break free from her restricted routine. Written and directed by Leticia Akel Escárate Cast: Daniela Leyton Escauriaza, Julia Lübbert Retuerto, René Miranda Díaz Executive producers: Pablo Greene, Claudia Huaiquimilla Producing company: Lanza Verde Co-producer: ComoPerro Films General producer: Ayelén Lonconao Vargas Director of Photography: Francisca Sáez Agurto Production designer: Francisca Celume Bustamante Sound: Juan Carlos Maldonado Dubó Editor: Valeria Hernández Postproduction : Filmo Estudios Distribution: OuatMedia OFFICIAL SELECTIONS & AWARDS SANFIC Santiago International Film Festival (Chile, 2023) Festival de Biarritz Amérique Latine (France, 2023) FECILS La Serena International Film Festival (Chile, 2023) Best Narrative Short Film Award Festival de Cine Nacional de Ñuble (Chile, 2024) FECICH Festival del Cine Chileno (Chile, 2024) Best Performance Award (Daniela Leyton) Audience Award Youth Jury Award San Diego Latino Film Festival (USA, 2024) Chicago Latino Film Festival (USA, 2024) Rio de Janeiro International Short Film Festival Curta Cinema (Brazil, 2024) Lebu International Film Festival (Chile, May 2024) Best Regional Short Film Award LALIFF Los Angeles Latino Film Festival (USA, 2024) Short Shorts Film Festival & Asia (Japan, 2024) Palm Springs International Short Fest (USA, 2024) Festival Cinéma en Liberté (France, 2024) The Americas Film Festival New York (USA, 2024) Lenola Film Festival Inventa un Film (Italy, 2024) Messaggio Importante Award HollyShorts Film Festival (USA, 2024) Live Action Short Film Award Nominee Lucania Film Festival (Italy, 2024) Sao Paulo International Short Film Festival Curta Kinoforum (Brazil, 2024) 10+ Audience Favorites Award Portobello Film Festival (UK, 2024) Semana de Cine de Lugo (Spain, 2024) FECISO Festival Internacional de Cine Social Castilla La Mancha (Spain, 2024) Primer Premio Plena Inclusión Festival Pachamama - Da Floresta aos Andes (Brazil, 2024) Film Festival Seize The Film (Serbia, 2024) Temecula Valley Film Festival (USA, 2024) Best of Fest Award Quito International Film Festival (Ecuador, 2024) Arica Nativa Film Festival (Chile, 2024) Lublin Film Festival (Poland, 2024) Rengo International Film Festival (Chile, 2024) Best Performance Award (Daniela Leyton) Felina Film Festival (Chile, 2024) Audience Award - National Short film BOGOSHORTS Bogotá International Short Film Festival (Colombia, 2024) FICH Chiloé International Film Festival (Chile, 2024) Honorable Mention Award - Regional Short Film Pedro Sienna Awards of the Chilean Film Academy (Chile, 2024) Best Short Film Award 2023 Skyline Benidorm Film Festival (Spain, 2025) Alexandria International Short Film Festival (Egypt, 2025) Lago Film Festival (Italy, 2025) Latam Short Film Festival (2025) Vitacura International Film Festival (Chile, 2025) Psaroloco International Film Festival (Greece, 2026)",
        "url": "https://vimeo.com/1229308303",
        "createdAt": "2026-09-22T16:52:56Z"
      },
      "author": {
        "id": "3162867",
        "displayName": "Leticia Akel",
        "url": "https://vimeo.com/leticiaakel"
      },
      "media": {
        "durationSeconds": 1202,
        "thumbnailUrl": "https://i.vimeocdn.com/video/2203986892-10016ddd6d51f70ce53082f98174a3c353ee94b1b40a3f5b7a29ac54075c2ebe-d_640?region=us"
      }
    },
    {
      "content": {
        "id": "1229666034",
        "title": "VOMIT",
        "text": "Wildcard addict on the run from trouble shows up bloodied and battered at the door of his home health aide ex-girlfriend, turning both their lives upside down in this super dark comedy about love, death, drugs, and ferrets. +++ A FILM BY Roi Cydulkin STARRING: Lindsey Normington Michael Buscemi Roi Cydulkin Tim Dundin Charlie Bodt Charles Nisan Jennifer Nisan Eddie & Mooch DIRECTOR OF PHOTOGRAPHY Julian Kapadia PRODUCED BY EJ Argenio, Roi Cydulkin PRODUCER Miles Skinner EXECUTIVE PRODUCERS Jon Yusupov, Finn Macmillan, Cecile Winckler, Brendan McHugh, Zak Williams 1st AD / ASSOCIATE PRODUCER Erik Bagger PRODUCTION DESIGNER Luke Carr COSTUME DESIGNER Jon Yusupov EDITOR Roi Cydulkin COMPOSER Eli Keszler CASTING BY Scotty Anderson, Mia Quinn 1st AC Christopher Figueroa 1st CAMERA ASSISTANT Rodrigo Milan Garce KEY GRIP Roberto De Cecco, Hunter Dunn GAFFER Yaniv Glaser, Nate PROP MASTER Patrick Parker HEAD MAKEUP ARTIST Maria Matarrese MAKEUP ARTIST Tiffany Brooks ON-SET SOUND MIXER Max Cooke LOCATIONS MANAGER William Senko DIT Leigh Ann Karetas SCRIPT SUPERVISOR Melanie Morgan, Anna Karmel PRODUCTION ASSISTANT James Elliott HEAD TRAINER (FERRET) Gloria Winship TRAINER (FERRET) Haley Deecken ASSISTANT EDITOR Charlie Horne COLORIST Mikey Pehanich EXECUTIVE COLOR PRODUCER Alexandra Lubrano ASSOCIATE COLOR PRODUCER Alex Ponce SUPERVISING SOUND EFFECT EDITOR George Castle & James Benn RE-RECORDING MIXER George Castle & James Benn DIALOGUE EDITOR Ben Sims SOUND EFFECTS EDITOR Rick Blything EXECUTIVE PRODUCER, AUDIO Savannah King SOUND DESIGNER Fred Pearson MIX ASSIST Rachel Scott FOLEY The Foley Walkers TITLE DESIGN Collin Fletcher OPTICAL PRINTING Purple Martin AUDIO POST PRODUCTION Harbor Picture Company ANIMALS PROVIDED BY Animal Actors / Sweet Sunshine PRODUCTION SUPPLIES PROVIDED BY Hard Out Production, Charlie Bodt VEHICLES PROVIDED BY Edge Auto Rental PARKING PROVIDED BY New Day Motor Club CAMERA EQUIPMENT PROVIDED BY TCS Film AUDIO EQUIPMENT PROVIDED BY Max Cooke Sound Inc. ADDITIONAL LENSES PROVIDED BY Handheld Films ADDITIONAL AJA COSTUME PROVIDED BY Veronika Vilim GRIP & ELECTRIC PROVIDED BY Corncob Productions Inc, Wits End Group IN MEMORY OF Billy Jones",
        "url": "https://vimeo.com/1229666034",
        "createdAt": "2026-09-23T16:11:58Z"
      },
      "author": {
        "id": "34457513",
        "displayName": "Roi Cydulkin",
        "url": "https://vimeo.com/user34457513"
      },
      "media": {
        "durationSeconds": 981,
        "thumbnailUrl": "https://i.vimeocdn.com/video/2204381903-7ac43b3916271e2b3cae701cd68b9aaece1eeb99368bbde66eb8f921a0e42221-d_640?region=us"
      }
    }
  ],
  "metadata": {
    "platform": "vimeo",
    "endpoint": "channel_videos",
    "cached": false,
    "stale": false,
    "age_s": 0,
    "fetched_at": "2026-01-01T12:00:00+00:00",
    "credits_charged": 5,
    "request_id": "7f3a9c2e5b1d4c8fa2e6d0b9c4f18e37"
  },
  "error": null
}
```

## Field mapping

How this endpoint's source fields become Onekey's [unified schema](https://onekey.dev/docs/schema.md). Fields the source lacks come back as `null`.

| Source path | Onekey field | Transform |
| --- | --- | --- |
| `id` | `content.id` | `toString` |
| `title` | `content.title` | - |
| `description` | `content.text` | `stripHtml` |
| `url` | `content.url` | `safeUrl` |
| `upload_date` | `content.createdAt` | `toIsoDate` |
| `user_id` | `author.id` | `toString` |
| `user_name` | `author.displayName` | - |
| `user_url` | `author.url` | `safeUrl` |
| `duration` | `media.durationSeconds` | `toNumber` |
| `thumbnail_large` | `media.thumbnailUrl` | `safeUrl` |

## Caching and freshness

- Fresh for about 2 minutes. Repeat calls in that window are served from cache and are free.
- Between 2 minutes and 15 minutes the cached copy is still served instantly and marked `stale: true` while Onekey refreshes it in the background.
- If the source is down when a refresh is needed, the last copy can be served for up to 1 hour more (marked stale).
- A "not found" is remembered for 1 minute and is free.
- The cache is shared across all customers, which is what keeps repeat calls cheap.

## What can go wrong

| Status | Code | What to do |
| --- | --- | --- |
| 401 | `unauthorized` | Check the `x-api-key` header. |
| 402 | `insufficient_credits` | [Add credits](https://onekey.dev/pricing); your balance must cover the price. |
| 404 | `not_found` | Unknown endpoint path. |
| 422 | `invalid_params` | Fix the parameters using the table above. Free. |
| 429 | `rate_limited` | Wait `Retry-After` seconds, then retry. |
| 502 | `upstream_error` | The source failed. Refunded; retry with backoff. |

See [Errors](https://onekey.dev/docs/errors.md) for the full list and retry guidance.

Status: stable (verified against the live source).