---
title: "Video Search"
method: POST
path: "/video-search"
---

# Video Search

`POST /video-search`

## Request

- Base URL: `https://api.octen.ai`
- URL: `https://api.octen.ai/video-search`
- Auth: one of:
  - HTTP bearer
  - API key in header `x-api-key`

Searches the web for videos from a text query. Contact us to request beta access.

## Request body

- VideoSearchRequest: Request body for the Video Search API.
  - `inputs` VideoSearchInput[], required: Input array carrying a text query (at most 1).
    - `type` 'text', required: The input type.
    - `data` string: The query content, max 500 characters.
  - `count` integer: Number of results to return.
  - `time_range` 'day' | 'week' | 'month' | 'year' | 'd' | 'w' | 'm' | 'y': Relative time window counting back from the current time, filtered by publish time. Mutually exclusive with `start_time`/`end_time` — if both are provided, `start_time`/`end_time` take precedence.
  - `start_time` string, date-time: Start time for filtering results by publish time. ISO 8601 format.
  - `end_time` string, date-time: End time for filtering results by publish time. ISO 8601 format.
  - `safesearch` 'off' | 'strict': Controls filtering of explicit/adult content. `off` disables filtering; `strict` drops all adult content.

## Response `200`

Successful video search response

- VideoSearchResponse
  - `code` integer: Business status code. 0 indicates success.
  - `msg` string: A message describing the result.
  - `request_id` string: The unique identifier for this request.
  - `data` VideoSearchData: The main response payload.
    - `results` VideoSearchResult[]: A list of video search results.
      - `title` string: The title of the video.
      - `url` string: The video URL.
      - `source_page` string: URL of the original page hosting the video.
      - `description` string: Server-generated text description of the video content.
      - `cover_url` string: Video cover image URL.
      - `duration_seconds` integer: Video duration in seconds.
      - `authors` string: Website name or author.
      - `time_published` string, date-time: Publish time in ISO 8601.
      - `time_last_crawled` string, date-time: Last crawl time in ISO 8601.
  - `meta` VideoSearchMeta: Additional metadata for the Video Search request.
    - `usage` VideoSearchUsage: Usage information for the Video Search request.
      - `num_search_queries` integer: Number of search queries executed.
    - `latency` number: Response time in milliseconds.
    - `warning` string, nullable: Warning message, if any.

## Other responses

- `400`: Missing parameter inputs — Returned when a required parameter is missing.
- `401`: Invalid API Key — Returned when the API key is missing or invalid.
- `403`: Insufficient balance in account — Returned when the account balance is insufficient to complete the request.
- `429`: Exceeding the rate limit — Returned when the request exceeds the configured rate limit.
- `500`: Internal error — Returned when an unexpected server-side error occurs.

---

[API](https://skmtc.dev/octen/apis/octen-api.md) - [All operations](https://skmtc.dev/octen/apis/octen-api/llms.txt) - [OpenAPI document](https://skmtc.dev/octen/apis/octen-api/revisions/aaa6caaf46b0?raw)