---
title: "Search videos by keyword"
method: GET
path: "/v1/raw/{platform}/search"
tags: ["Raw"]
---

# Search videos by keyword

`GET /v1/raw/{platform}/search`

## Request

- Base URL: `https://api.virlo.ai`
- URL: `https://api.virlo.ai/v1/raw/{platform}/search`
- Auth: HTTP bearer

Keyword search on the platform, in the platform's own ranking order. YouTube returns Shorts only and Instagram returns Reels only. One platform page per call. Follow `pagination.next_cursor` for more; page sizes are set by the platform. Live data fetched at request time, not stored by Virlo. Typical latency is a few seconds, up to about 25 s. 1 credit ($0.01) per call, including an empty page. Errors (400, 404, 5xx) are not billed.

## Path parameters

- `platform` 'tiktok' | 'youtube' | 'instagram', required

## Query parameters

- `cursor` string
- `q` string, required

## Response `200`

- RawVideoPageResponseDto
  - `data` RawVideoDto[], required: One upstream page. Can be empty (still billed).
    - `id` string, required: Platform video ID (TikTok numeric ID, YouTube video ID, Instagram shortcode).
    - `platform` 'tiktok' | 'youtube' | 'instagram', required
    - `url` string, required
    - `caption` string, nullable, required
    - `hashtags` string[], required: Hashtags without #, lowercased. Empty when none.
    - `published_at` string, date-time, nullable, required: Publish time, ISO 8601 UTC.
    - `duration_seconds` number, nullable, required: Length in seconds.
    - `thumbnail_url` string, nullable, required: Thumbnail URL on the platform CDN. These links can expire.
    - `author` RawAuthorRefDto, required
      - `id` string, nullable, required: Platform user or channel ID.
      - `handle` string, nullable, required: Handle without the leading @.
      - `display_name` string, nullable, required
      - `avatar_url` string, nullable, required: Avatar image URL on the platform CDN. These links can expire.
      - `verified` boolean, nullable, required
    - `stats` RawVideoStatsDto, required
      - `views` number, nullable, required
      - `likes` number, nullable, required
      - `comments` number, nullable, required
      - `shares` number, nullable, required
      - `saves` number, nullable, required
    - `sound` RawSoundDto, required
      - `id` string, nullable, required: Platform sound/audio ID.
      - `title` string, nullable, required
      - `artist` string, nullable, required
    - `platform_data` object, required: Platform-only fields, snake_case. Keys differ by platform and may be absent when the platform does not return them.
  - `pagination` RawPaginationDto, required
    - `next_cursor` string, nullable, required: Pass as `cursor` to get the next page. Null on the last page.
    - `has_more` boolean, required: True when next_cursor is set.

## Other responses

- `400`: Invalid input (`validation_error`), operation not offered on this platform (`unsupported_platform`), or a bad cursor (`invalid_cursor`). Not billed.
- `401`: Missing or invalid API key (`missing_api_key` / `invalid_api_key`)
- `402`: Not enough credits (`insufficient_credits`).
- `429`: Rate limit exceeded (`rate_limit_exceeded`); see the Retry-After header
- `502`: The platform did not return data (`upstream_error`). Retry. Not billed.
- `503`: Temporarily unavailable (`service_unavailable`). Retry later. Not billed.
- `504`: The platform took too long to answer (`request_timeout`). Retry. Not billed.

---

[API](https://skmtc.dev/virlo/apis/virlo-public-api.md) · [All operations](https://skmtc.dev/virlo/apis/virlo-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/virlo/apis/virlo-public-api/revisions/3b69c6145087?raw)