> For the complete documentation index, see [llms.txt](https://docs.agenticflow.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.agenticflow.ai/reference/nodes/search_video_in_pexels.md).

# Search video in Pexels

**Action ID:** `search_video_in_pexels`

## Description

Search video in Pexels.

## Input Parameters

| Name        | Type    | Required | Default | Description                                                           |
| ----------- | ------- | :------: | ------- | --------------------------------------------------------------------- |
| query       | string  |     ✓    | -       | The search query (e.g., "ocean", "tigers", "cooking")                 |
| orientation | string  |     -    | null    | Desired video orientation: `landscape`, `portrait`, or `square`       |
| size        | string  |     -    | null    | Minimum video size: `large` (4K), `medium` (Full HD), or `small` (HD) |
| page        | integer |     -    | 1       | The page number you are requesting (must be > 0)                      |
| per\_page   | integer |     -    | 15      | Number of items per page (maximum 80)                                 |

<details>

<summary>View JSON Schema</summary>

```json
{
  "description": "Search video in Pexels action input.",
  "properties": {
    "query": {
      "description": "The search query. Ocean, Tigers, Pears, etc.",
      "title": "The search query.",
      "type": "string"
    },
    "orientation": {
      "anyOf": [
        {
          "enum": [
            "landscape",
            "portrait",
            "square"
          ],
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Desired video orientation. The current supported orientations are: `landscape`, `portrait` or `square`.",
      "title": "Orientation"
    },
    "size": {
      "anyOf": [
        {
          "enum": [
            "large",
            "medium",
            "small"
          ],
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Minimum video size. The current supported sizes are: `large`(4K), `medium`(Full HD) or `small`(HD).",
      "title": "Minimum video size"
    },
    "page": {
      "anyOf": [
        {
          "exclusiveMinimum": 0,
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": 1,
      "description": "The page number you are requesting.",
      "title": "The page number you are requesting."
    },
    "per_page": {
      "anyOf": [
        {
          "exclusiveMinimum": 0,
          "maximum": 80,
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": 15,
      "description": "Number of items per page.",
      "title": "Number of items per page."
    }
  },
  "required": [
    "query"
  ],
  "title": "SearchVideoInPexelsActionInput",
  "type": "object"
}
```

</details>

## Output Parameters

| Name           | Type    | Description                                                 |
| -------------- | ------- | ----------------------------------------------------------- |
| videos         | array   | Array of video objects matching the search criteria         |
| page           | integer | Current page number                                         |
| per\_page      | integer | Number of items returned per page                           |
| total\_results | integer | Total number of videos found for the search query           |
| prev\_page     | string  | URL to the previous page of results (null if on first page) |
| next\_page     | string  | URL to the next page of results (null if on last page)      |

<details>

<summary>View JSON Schema</summary>

```json
{
  "$defs": {
    "PexelsVideo": {
      "description": "Pexels video model.",
      "properties": {
        "id": {
          "title": "Id",
          "type": "integer"
        },
        "width": {
          "title": "Width",
          "type": "integer"
        },
        "height": {
          "title": "Height",
          "type": "integer"
        },
        "url": {
          "title": "Url",
          "type": "string"
        },
        "image": {
          "title": "Image",
          "type": "string"
        },
        "full_res": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Full Res"
        },
        "duration": {
          "title": "Duration",
          "type": "integer"
        },
        "video_files": {
          "items": {
            "additionalProperties": true,
            "type": "object"
          },
          "title": "Video Files",
          "type": "array"
        }
      },
      "required": [
        "id",
        "width",
        "height",
        "url",
        "image",
        "full_res",
        "duration",
        "video_files"
      ],
      "title": "PexelsVideo",
      "type": "object"
    }
  },
  "description": "Search video in pexels action output.",
  "properties": {
    "videos": {
      "description": "Videos",
      "items": {
        "$ref": "#/$defs/PexelsVideo"
      },
      "title": "Videos",
      "type": "array"
    },
    "page": {
      "description": "Current page",
      "title": "Current page",
      "type": "integer"
    },
    "per_page": {
      "description": "Items per page",
      "title": "Items per page",
      "type": "integer"
    },
    "total_results": {
      "description": "Total results",
      "title": "Total results",
      "type": "integer"
    },
    "prev_page": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Previous page url",
      "title": "Previous page url"
    },
    "next_page": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Next page url",
      "title": "Next page url"
    }
  },
  "required": [
    "videos",
    "page",
    "per_page",
    "total_results"
  ],
  "title": "SearchVideoInPexelsActionOutput",
  "type": "object"
}
```

</details>

## How It Works

This node searches the Pexels video library using your specified query and filter criteria. The search query is sent to the Pexels API, which returns a paginated list of matching videos. You can filter results by orientation (landscape, portrait, square) and minimum video quality (small/HD, medium/Full HD, large/4K). The node returns detailed metadata for each video including multiple download URLs in different resolutions and formats, along with pagination information to navigate through large result sets.

## Usage Examples

### Example 1: Basic Video Search

**Input:**

```
query: "ocean waves"
page: 1
per_page: 15
```

**Output:**

```
videos: [
  {
    id: 3571264,
    width: 3840,
    height: 2160,
    url: "https://www.pexels.com/video/3571264/",
    image: "https://images.pexels.com/videos/3571264/pictures/preview-0.jpg",
    duration: 15,
    video_files: [...]
  },
  ...
]
total_results: 342
page: 1
per_page: 15
```

### Example 2: Portrait Video Search for Social Media

**Input:**

```
query: "cooking tutorial"
orientation: "portrait"
size: "medium"
per_page: 10
```

**Output:**

```
videos: [
  {
    id: 4626456,
    width: 1080,
    height: 1920,
    url: "https://www.pexels.com/video/4626456/",
    duration: 22,
    video_files: [...]
  },
  ...
]
total_results: 89
```

### Example 3: High-Quality Landscape Videos

**Input:**

```
query: "city timelapse"
orientation: "landscape"
size: "large"
page: 2
per_page: 5
```

**Output:**

```
videos: [
  {
    id: 2695393,
    width: 3840,
    height: 2160,
    duration: 30,
    video_files: [...]
  },
  ...
]
page: 2
next_page: "https://api.pexels.com/videos/search?page=3&per_page=5"
```

## Common Use Cases

* **Video Background Selection**: Find professional stock videos for website backgrounds, hero sections, or presentation slides
* **Social Media Content**: Search for vertical (portrait) videos optimized for Instagram Stories, TikTok, or Reels
* **Marketing Materials**: Source high-quality stock footage for advertisements, promotional videos, or product demos
* **Content Creation**: Find B-roll footage to enhance vlogs, documentaries, or educational content
* **E-commerce**: Locate product-related videos like lifestyle shots, unboxing footage, or usage demonstrations
* **Presentation Design**: Search for thematic videos to make presentations more engaging and professional
* **Video Editing Projects**: Build a library of stock footage clips for editing projects by searching multiple keywords

## Error Handling

| Error Type              | Cause                                   | Solution                                                        |
| ----------------------- | --------------------------------------- | --------------------------------------------------------------- |
| Invalid Query           | Empty or missing search query parameter | Provide a non-empty query string with relevant keywords         |
| Invalid Orientation     | Orientation value not in allowed list   | Use only "landscape", "portrait", or "square"                   |
| Invalid Size            | Size value not in allowed list          | Use only "small" (HD), "medium" (Full HD), or "large" (4K)      |
| Invalid Page Number     | Page number is zero or negative         | Use page numbers starting from 1                                |
| Per Page Limit Exceeded | per\_page value greater than 80         | Set per\_page to a value between 1 and 80                       |
| API Rate Limit          | Too many requests in short time period  | Implement delays between requests or cache results              |
| No Results Found        | Search query returns no matching videos | Try different keywords, remove filters, or broaden search terms |

## Notes

* **Free Stock Videos**: Pexels provides completely free stock videos that can be used for commercial and personal projects without attribution
* **Pagination**: Use the page and per\_page parameters to navigate through large result sets. The maximum per\_page value is 80
* **Video Quality Filters**: The size parameter filters by minimum quality - "large" returns 4K videos, "medium" returns Full HD (1080p), and "small" returns HD (720p)
* **Multiple File Formats**: Each video in the results includes a video\_files array with multiple download URLs in different resolutions and formats (MP4, etc.)
* **Orientation Filter**: Use orientation filtering when you need specific aspect ratios - landscape for widescreen, portrait for mobile/vertical video, square for 1:1 content
* **Duration Information**: The duration field shows video length in seconds, helping you select appropriately-sized clips for your project
* **Search Optimization**: Use specific, descriptive keywords for better results. Combine nouns with descriptive adjectives like "sunset beach" rather than just "beach"
* **Result Caching**: Consider caching search results to reduce API calls, especially for popular or repeated queries