# vimeo.user_videos

**stable** **Advanced**

Public videos uploaded by a Vimeo user (latest page).

`GET /v1/vimeo/user_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 |
| --- | --- | --- | --- | --- | --- |
| `user` | string | yes | (required) | Vimeo username/slug, e.g. staff | max 60 chars; must match `[A-Za-z0-9_\-]{1,60}`; trimmed, leading @ removed |

## Request

```bash
curl "https://api.onekey.dev/v1/vimeo/user_videos?user=staff" \
  -H "x-api-key: YOUR_API_KEY"
```

```python
import requests

res = requests.get(
    "https://api.onekey.dev/v1/vimeo/user_videos",
    params={"user": "staff"},
    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({ user: "staff" });
const res = await fetch(`https://api.onekey.dev/v1/vimeo/user_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": "1202208321",
        "title": "Copy of How Wise scaled its employee communications into a company-wide “Mission”",
        "text": "Wise is a global organization with over 5,000 employees spread around the world. The internal communications challenge? Ensuring every employee feels connected. Discover how Vimeo became the right tool to create a clear strategy for organizing and presenting video content. ✨ In this customer story, learn how Wise leveraged Vimeo to: Maintain connection: Create content that makes employees feel \"in the room\" whether they join a live call or watch the recording afterward. Build an amazing archive: Establish a clear strategy by creating dedicated folders for every recorded event, building a comprehensive, high-quality archive of all content ever produced. Centralized access: Provide employees with one single tool where they can go to check all of the internal video content. 📲 Improve accessibility: Ensure video is more accessible and of higher quality across the entire organization. If you need a reliable, centralized platform to connect a large, distributed global workforce and build an easily accessible video archive, this is a must-watch! Start for free #Vimeo #customerstory #wise #internalcomms #employeeengagement #globalworkforce #videoarchive #videoplatform #communication 💡 --- Transcript: There's something really powerful about being able to kind of pop into a call live, but then know if you're not able to do that, you then still have access to that same recording and it's like you were in the room by watching it even afterwards. WISE as an organization is now over 5,000 employees and we're spread around the world. But what this means for internal comms is that we wanna make sure that everyone really feels connected. Having a clear strategy for organizing and presenting content wasn't something that was always there. Part of making video more accessible to people and higher quality has been just using the right tools. That's where Vimeo comes in for us. We make sure that we create folders with every single event that we have recorded and we've created this amazing archive. Having that one tool where people can go and check all of the content that we've ever produced is just amazing.",
        "url": "https://vimeo.com/1202208321",
        "createdAt": "2026-06-17T12:41:41Z"
      },
      "author": {
        "id": "152184",
        "displayName": "Vimeo",
        "url": "https://vimeo.com/staff"
      },
      "media": {
        "durationSeconds": 60,
        "thumbnailUrl": "https://i.vimeocdn.com/video/2169774974-8d42be084226f8429851f58da033492113e7ad54a353c636d7ba237404e5e50b-d_640?region=us"
      }
    },
    {
      "content": {
        "id": "1146062919",
        "title": "Behind the scenes of Vimeo's Short Film Grant Program",
        "text": null,
        "url": "https://vimeo.com/1146062919",
        "createdAt": "2025-12-12T15:48:16Z"
      },
      "author": {
        "id": "152184",
        "displayName": "Vimeo",
        "url": "https://vimeo.com/staff"
      },
      "media": {
        "durationSeconds": 87,
        "thumbnailUrl": "https://i.vimeocdn.com/video/2098174665-cc979d3665107e0af390938cdba29ef87bd93267a1452170722bf4c2238ca52f-d_640?region=us"
      }
    }
  ],
  "metadata": {
    "platform": "vimeo",
    "endpoint": "user_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).