/videos/list¶
Return a list of videos.
Parameters¶
- tags (optional) : string
Restrict the search to videos tagged with these tags. Multiple tags should be comma-separated.
- tags_mode (optional) : string
Tags search mode:
- all
A video will only be listed if it has all tags specified in the tags parameter.
- any
A video will be listed if it has at least one tag specified in the tags parameter.
Default is all.
- search (optional) : string
Case-insensitive search in the author, description, link, md5, tags, title, video_key fields and custom fields. Parameter can also include comma-separated list of fields that specifies where search should be done.
Search parameter can be specified in the following ways:
- search
Only videos that contain search string in at least one of the default search fields will be listed. Default search fields are: author, description, tags, title and video_key.
- search:*
Only videos that contain search string in at least one of the search fields will be listed. Search fields are: author, description, link, md5, tags, title and video_key.
- search:field1[,field2]
Only videos that contain search string in at least one of the fields specified in the list will be listed. Multiple fields in the list must be comma-separated. Allowed fields are: author, description, link, md5, tags, title and video_key.
- search:custom.*
Only videos that contain search string in at least one of the custom fields will be listed.
- search:custom.field1[,custom.field2]
Only videos that contain search string in at least one of the custom fields specified in the list will be listed. Multiple fields in the list must be comma-separated.
- search:field1[,field2],custom.field1[,custom.field2]
Only videos that contain search string in at least one of the search or custom fields specified in the list will be listed. Multiple fields in the list must be comma-separated.
An * wildcard field can be used if search should be done in all search fields and/or all custom search fields. For example:
search:*,custom.field1,custom.field2
search:field1,field2,custom.*
search:*,custom.*
- mediatypes_filter (optional): string
List only videos with the specified media types. Filter string can include the following media types:
- unknown
List only videos with media type unknown.
- audio
List only videos with media type audio.
- video
List only videos with media type video.
Each media type in the filter string should be separated by a comma. By default media types filter is not applied.
- statuses_filter (optional): string
List only videos with the specified statuses. Filter string can include the following statuses:
- processing
List only videos with status processing.
- ready
List only videos with status ready.
- updating
List only videos with status updating.
- failed
List only videos with status failed.
Each status in the filter string should be separated by a comma. By default statuses filter is not applied.
- order_by (optional) : string
Specifies parameters by which returned result should be ordered. Parameter sort order can be specified by appending :asc for an ascending sort order or :desc for a descending one to the parameter name. Default sort order is ascending and can be omitted. Multiple parameters should be separated by a comma.
Result can be ordered by the following parameters: key, title, description, date, link, author, size, duration, views and status. Default is date:asc.
- start_date (optional) : unsigned integer
Video creation date starting from which videos list should be returned. Date must be an UTC date in Unix timestamp format.
- end_date (optional) : unsigned integer
Video creation date until (and including) which videos list should be returned. Date must be an UTC date in Unix timestamp format.
- result_limit (optional): unsigned integer
Specifies maximum number of videos to return. Default is 50. Maximum result limit is 1000.
- result_offset (optional): unsigned integer
Specifies how many videos should be skipped at the beginning of the result set. Default is 0.
Example response¶
<?xml version="1.0" encoding="UTF-8"?>
<response>
<status>ok</status>
<limit>50</limit>
<offset>100</offset>
<total>122</total>
<videos total="22">
<video key="yYul4DRz">
<author>Bits on the Run</author>
<custom>
<param1>value 1</param1>
<param2>value 2</param2>
</custom>
<date>1225962900</date>
<description>New video</description>
<duration>12.0</duration>
<error>
<message>Unsupported format</message>
</error>
<link>http://www.bitsontherun.com</link>
<md5>b2d7312bd39cc60e9facc8ed3cbb6418</md5>
<mediatype>video</mediatype>
<size>29478520</size>
<status>ready</status>
<tags>new, video</tags>
<title>New test video</title>
<views>123</views>
</video>
...
</videos>
</response>
Response parameters¶
- /response/status : string
Call execution status. Set to ok if call executed successfully.
- /response/limit : unsigned integer
Maximum number of videos that should be return. As specified in the result_limit request parameter.
- /response/offset : unsigned integer
Number of videos that should be skipped at the beginning of the result set. As specified in the result_offset request parameter.
- /response/total : unsigned integer
Total number of videos available.
- /videos/@total : unsigned integer
Total number of returned videos.
- //video/@key : string
Video key.
- //video/author : string
Author of the video.
- //video/custom/param1 : string
User defined parameter.
- //video/date : signed integer
Video creation date. Date is an UTC date in Unix timestamp format.
- //video/description : string
Description of the video.
- //video/duration : float
Duration of the video in seconds.
- //video/link : string
The URL of the web page where this video is published.
- //video/md5 : string
MD5 hash of the original file.
- //video/mediatype : string
Content media type:
- unknown
Media type is unknown.
- audio
Media type is audio.
- video
Media type is video.
- //video/size : unsigned integer
Combined size of all conversions created for this video in bytes.
- //video/status : string
Video status:
- processing
Original file or default conversion is being processed.
- ready
Video ready for streaming (original and default conversion are ready).
- updating
New (re-uploaded) original file is being processed. Previous original file and default conversion are ready for streaming.
- failed
Processing of the original file or default conversion has failed.
- //video/error : string
Not empty if processing of the initial or re-uploaded original file or their default conversion has failed.
- //video/error/message : string
Error message.
When //video/status is failed, error message corresponds to the initially uploaded original file or its default conversion, or to the last re-uploaded original file or its default conversion (if initial upload also has failed).
When //video/status is ready, error message corresponds to the last re-uploaded original file or its default conversion.
- //video/tags : string
Tags of the video.
- //video/title : string
Title of the video.
- //video/views : unsigned integer
Total video views since video has been created.