---
title: "Full-text search for KOLs with advanced filtering and pagination"
method: POST
path: "/api/v1/search/inbound/full-text-by-page"
tags: ["Search"]
---

# Full-text search for KOLs with advanced filtering and pagination

`POST /api/v1/search/inbound/full-text-by-page`

## Request

- Base URL: `https://api.kolect.com`
- URL: `https://api.kolect.com/api/v1/search/inbound/full-text-by-page`
- Auth: HTTP bearer

Performs a full-text search on video titles to find Key Opinion Leaders (KOLs).
Supports complex query syntax, result ranking, and cursor-based pagination.

**Query Syntax (PostgreSQL tsquery format):**
- **Basic match:** `camera`
- **Multi-word (any):** `camera tripod` (equivalent to `camera | tripod`)
- **Require all:** `camera & tripod`
- **Exclude:** `camera & !phone`
- **Phrase search:** `"vlog camera setup"`

## Request body

- object
  - `query` string: Natural language query with optional operators.
  - `limit` integer: Maximum number of videos to process. Use -1 for unlimited.
  - `similarity_threshold` number, float: Minimum similarity score (0-1) for a video to be included when ranking is enabled.
  - `ranking_mode` 'sum' | 'max': How to aggregate similarity scores for ranking KOLs.
  - `enable_ranking` boolean: If true, enables similarity ranking using `ts_rank_cd`.
  - `top_kols` integer: If specified, returns only the top N KOLs based on the ranking.
  - `cursor` string: Base64 encoded cursor for KOL-level pagination.
  - `page_size` integer: Number of KOLs to return per page.
  - `min_videos` integer: Minimum number of matched videos a KOL must have to be included.
  - `max_videos` integer: Maximum number of matched videos to return per KOL.

## Response `200`

Search completed successfully.

- object
  - `success` boolean
  - `kols` KolResponse[]
    - `kol_id` string
    - `name` string
    - `avatar` string
    - `followers` number
    - `country` string
    - `channel` string
    - `email` string
    - `matched_video_titles` object[]
      - `video_id` string
      - `title` string
      - `matching_words` string
      - `similarity` number
    - `median_views` number
    - `average_views` number
    - `profile_url` string
  - `matched_count` integer
  - `total_kols_found` integer
  - `videos_searched` integer
  - `time_elapsed` number
  - `next_cursor` string, nullable
  - `has_more` boolean

## Other responses

- `400`: Bad request due to invalid input.
- `500`: Internal server error.

---

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