Get Videos

Returns all videos from the system that match the specified criteria

GET /videos

cURL

cURL

curl --request GET \
  --url https://www.topyappers.com/api/v1/videos \
  --header 'x-ty-api-key: <api-key>'

200

{
  "data": [
    {
      "iv_id": "<string>",
      "user_id": "<string>",
      "user_handle": "<string>",
      "video_id": "<string>",
      "source": "tiktok",
      "comments": 123,
      "description": "<string>",
      "hashtags": [
        "<string>"
      ],
      "likes": 123,
      "shares": 123,
      "subtitles": [
        {}
      ],
      "user_followers": 123,
      "views": 123,
      "date_created_timestamp": 123
    }
  ],
  "pagination": {
    "page": 123,
    "perPage": 123,
    "total": 123,
    "totalPages": 123
  }
}

Sorting

The Videos API accepts optional query parameters sortBy and sortOrder. They control which videos rank first on each page—critical when you are not filtering by a single creator.

Use sortOrder=asc or sortOrder=desc. If omitted, the API defaults to sorting by views in descending order.

Allowed sortBy values

sortBy	Description
views	View count (default field when sortBy is omitted)
likes	Like count
shares	Share count
user_followers	Creator follower count at index time
date_created	When the video was created; sorted using our indexed timestamp (newest or oldest first depending on sortOrder)

Examples

Newest videos first:

sortBy=date_created&sortOrder=desc

Highest engagement (views) first:

sortBy=views&sortOrder=desc

Authorizations

x-ty-api-key · string · header · required

API key for TopYappers API authentication

Query Parameters

userHandle · string

Filter videos by specific user handle

userFollowersMin · integer

Minimum number of followers the video creator must have

userFollowersMax · integer

Maximum number of followers the video creator can have

viewsMin · integer

Minimum number of views the video must have

viewsMax · integer

Maximum number of views the video can have

likesMin · integer

Minimum number of likes the video must have

likesMax · integer

Maximum number of likes the video can have

commentsMin · integer

Minimum number of comments the video must have

commentsMax · integer

Maximum number of comments the video can have

sharesMin · integer

Minimum number of shares the video must have

sharesMax · integer

Maximum number of shares the video can have

hashtags · string

Filter by hashtags (comma-separated for multiple)

textSearch · string

Search for keywords in video description or caption

sortOrder · enum<string>

Sort direction: asc or desc. Default: desc (e.g. highest views first when sortBy=views).

Available options: asc, desc

sortBy · enum<string>

Field to sort by. Default: views. Use date_created for newest/oldest video order.

Available options: user_followers, views, shares, likes, date_created

page · integer

Page number for pagination

Required range: x >= 1

perPage · integer

Number of results per page

Required range: 1 <= x <= 100

Response

200

application/json

Videos response

data · object[]

Show child attributes

pagination · object

Show child attributes