# 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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.agenticflow.ai/reference/nodes/search_video_in_pexels.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.