> ## Documentation Index
> Fetch the complete documentation index at: https://docs.topyappers.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Videos

> Returns all videos from the system that match the specified criteria

## 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:

```bash theme={null}
sortBy=date_created&sortOrder=desc
```

Highest engagement (views) first:

```bash theme={null}
sortBy=views&sortOrder=desc
```


## OpenAPI

````yaml GET /api/v1/videos
openapi: 3.1.0
info:
  title: Videos API
  description: >-
    TopYappers Videos API for searching and filtering video content from
    creators
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://api.topyappers.com
security:
  - apiKeyAuth: []
paths:
  /api/v1/videos:
    get:
      description: Returns all videos from the system that match the specified criteria
      parameters:
        - name: userHandle
          in: query
          description: Filter videos by specific user handle
          schema:
            type: string
          example: mrbeast
        - name: userFollowersMin
          in: query
          description: Minimum number of followers the video creator must have
          schema:
            type: integer
          example: 10000
        - name: userFollowersMax
          in: query
          description: Maximum number of followers the video creator can have
          schema:
            type: integer
          example: 1000000
        - name: viewsMin
          in: query
          description: Minimum number of views the video must have
          schema:
            type: integer
          example: 5000
        - name: viewsMax
          in: query
          description: Maximum number of views the video can have
          schema:
            type: integer
          example: 500000
        - name: likesMin
          in: query
          description: Minimum number of likes the video must have
          schema:
            type: integer
          example: 100
        - name: likesMax
          in: query
          description: Maximum number of likes the video can have
          schema:
            type: integer
          example: 50000
        - name: commentsMin
          in: query
          description: Minimum number of comments the video must have
          schema:
            type: integer
          example: 10
        - name: commentsMax
          in: query
          description: Maximum number of comments the video can have
          schema:
            type: integer
          example: 5000
        - name: sharesMin
          in: query
          description: Minimum number of shares the video must have
          schema:
            type: integer
          example: 5
        - name: sharesMax
          in: query
          description: Maximum number of shares the video can have
          schema:
            type: integer
          example: 1000
        - name: hashtags
          in: query
          description: Filter by hashtags (comma-separated for multiple)
          schema:
            type: string
          example: fashion,streetwear,ootd
        - name: textSearch
          in: query
          description: Search for keywords in video description or caption
          schema:
            type: string
          example: workout routine
        - name: sortOrder
          in: query
          description: >-
            Sort direction: asc or desc. Default: desc (e.g. highest views first
            when sortBy=views).
          schema:
            type: string
            enum:
              - asc
              - desc
          example: desc
        - name: sortBy
          in: query
          description: >-
            Field to sort by. Default: views. Use date_created for newest/oldest
            video order.
          schema:
            type: string
            enum:
              - user_followers
              - views
              - shares
              - likes
              - date_created
          example: views
        - name: page
          in: query
          description: Page number for pagination
          schema:
            type: integer
            minimum: 1
          example: 1
        - name: perPage
          in: query
          description: Number of results per page
          schema:
            type: integer
            minimum: 1
            maximum: 100
          example: 20
      responses:
        '200':
          description: Videos response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Video'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitExceeded'
components:
  schemas:
    Video:
      type: object
      required:
        - iv_id
        - user_id
        - user_handle
        - video_id
        - source
        - comments
        - description
        - hashtags
        - likes
        - shares
        - subtitles
        - user_followers
        - views
        - date_created_timestamp
      properties:
        iv_id:
          type: string
          description: Internal video identifier
        user_id:
          type: string
          description: Platform user identifier
        user_handle:
          type: string
          description: Handle of the creator who posted the video
        video_id:
          type: string
          description: Platform video identifier
        source:
          type: string
          enum:
            - tiktok
            - instagram
            - youtube
          description: Data source / platform
        comments:
          type: integer
          description: Number of comments on the video
        description:
          type: string
          description: Video description or caption
        hashtags:
          type: array
          items:
            type: string
          description: Hashtags associated with the video
        likes:
          type: integer
          description: Number of likes the video has received
        shares:
          type: integer
          description: Number of times the video has been shared
        subtitles:
          type:
            - array
            - 'null'
          items:
            type: object
          description: Subtitles data if available
        user_followers:
          type: integer
          description: Number of followers the creator has
        views:
          type: integer
          description: Number of views the video has received
        date_created_timestamp:
          type: number
          description: Unix timestamp (seconds) when the video was created
    Pagination:
      type: object
      properties:
        page:
          type: integer
          description: Current page number
        perPage:
          type: integer
          description: Number of items per page
        total:
          type: integer
          description: Total number of items
        totalPages:
          type: integer
          description: Total number of pages
    Error:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: integer
          format: int32
        message:
          type: string
    RateLimitExceeded:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: integer
          format: int32
          example: 429
        message:
          type: string
          example: Rate limit exceeded. Please try again later.
        retryAfter:
          type: integer
          description: Number of seconds to wait before retrying
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: x-ty-api-key
      description: API key for TopYappers API authentication

````