Collection Representation

If your API request returns more than one resource, the Vimeo API wraps them in the collection representation. This JSON wrapper includes additional useful information, such as pagination, counts and more.

Field Type Description
data array An array of resource representations. This is the primary content of the collection.
total number The total amount of resources for this endpoint, summed across all pages.
page number The current page of resources.
per_page number The amount of resources to include in each page of data.
pagination object An object detailing how to request additional pages in this collection. See our pagination docs for additional information.


Sometimes your collection might be very large. Returning thousands of resources in a single API request can become prohibitively slow, so we split the response into multiple requests. Each request returns a single page of information, and you can increase the amount of items per page with the per_page parameter (max 100).

To request pages beyond the first, we highly recommend you use the built in pagination URI's. These are included in every collection response, and tell you the exact API call to make to receive the next, previous, first and last pages

"paging": {
 "next": "/users/101193/videos?page=2&per_page=10",
 "previous": null,
 "first": "/users/101193/videos?page=1&per_page=10",
 "last": "/users/101193/videos?page=3&per_page=10"

Common Headers and Parameters

JSON Filter

Our JSON responses can be very large. With a simple parameter you can reduce the size of the responses, and dramatically increase the performance of your API requests. This feature is surprisingly powerful for how simple it is. Simply provide a comma separated whitelist of fields, and all unwanted information will be stripped away.

 "uri": "/users/dashron",
 "name": "Aaron"

Need to see nested fields? Separate each tier with a period!

 "metadata": {
 "connections": {
 "activities": {
 "uri": "/users/8607249/activities",
 "options": ["GET"]

What if your information is in an array? Those work seamlessly.

 "websites": [{
 "name": "facebook"
 "name": "twitter"
 "name": "homepage"

We have some awesome optimizations around the fields filter. If you don't want a field, we won't build it. So you should see significantly faster requests if you leave out pictures, users and other related information.


Some resources are sortable. We specify valid sorts in the endpoint documentation. All sortable resources accept the direction parameter which must be either asc or desc. The default sort direction is desc.

For example, to list a user's uploaded videos with the oldest first:


Resource filter

Some collections support reducing a result set into subsets of that data. We specify valid filters in the endpoint documentation. All filterable resources accept the filter parameter, and some resources accept additional related filter parameters.

The following example will only show featured channels


Content rating

Content filter is a specific type of resource filter, available on all video resources. Any videos that do not match one of the provided ratings will be excluded from the list of videos.

You enable content rating with the parameter filter=content_rating. Specific ratings are then provided through the parameter filter_content_rating=[list,of,filters]

Valid ratings include:


For example, you will find safe and unrated Staff Pick videos at


Batch requests

Some API endpoints are designed to support batch API requests. A batch API request affects many different resources. This request may add new resources, edit many resources or interact with many different resources in a single API call.

The parameters must be provided via the request body as a JSON array of objects. The following example demonstrates this by adding many categories to a video:

 "category": "animation"
}, {
 "category": "talks"

HTTP Method override

Some programming languages do not support the HTTP PATCH method. To work around this limitation you can use the HTTP POST method alongside the following header.

X-HTTP-Method-Override: PATCH

Send Feedback