# Search videos

Search public YouTube videos by query.

ID: task:youtube_general_search_v1 · Region: global · Status: available

catalog_version: 938eb1e3bdb6476050bf2983e6e8db1edcf9f0942d16c7ebd2029dcd28295afe
updated_at: 2026-10-21T10:40:52.196893+00:00

Search public YouTube videos by query.

Dataset releases define historical periods; live reads describe request-time data and do not guarantee completeness.

Docs: https://docs.kleardata.ai/capabilities/task%3Ayoutube_general_search_v1

## POST /v1/search

legacy · available · api_key, oauth

REST requires a customer API Key; MCP requires an enabled authenticated server; CLI requires its published artifact and command.

续页：首次不传 `page_token`，之后把 `pagination.next_page_token` 原样传回。
`page_token` 是不透明串，不要自行构造或修改。

4 Credits per successful task

Where the request declares idempotency_key, reuse it for the same operation; metadata GET is read-only.

A pending response supplies a result/status reference. Read it first; do not automatically resubmit paid execution after a timeout or ambiguous result. Correct 401/403/422 errors before retrying.

### Input schema / 输入契约

```json
{
  "$defs": {
    "Schema1": {
      "additionalProperties": false,
      "description": "Common filter names with source-specific values checked after parsing.\n\n``sort`` stays a bounded string here because ``SearchSourceDefinition``\nowns each provider's vocabulary.",
      "properties": {
        "sort": {
          "enum": [
            "latest",
            "popularity",
            "relevance"
          ]
        },
        "time_range": {
          "enum": [
            "day",
            "hour",
            "month",
            "week",
            "year"
          ]
        }
      },
      "required": [],
      "type": "object"
    },
    "Schema2": {
      "additionalProperties": false,
      "description": "Exactly one public image reference accepted by the Search API.",
      "properties": {
        "asset_id": {
          "anyOf": [
            {
              "maxLength": 128,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "base64": {
          "anyOf": [
            {
              "maxLength": 8388608,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "url": {
          "anyOf": [
            {
              "maxLength": 2048,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        }
      },
      "type": "object"
    }
  },
  "additionalProperties": false,
  "description": "Public request shape shared by text, image, and hybrid sources.",
  "properties": {
    "filters": {
      "$ref": "#/$defs/Schema1"
    },
    "image": {
      "anyOf": [
        {
          "$ref": "#/$defs/Schema2"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "max_credits": {
      "anyOf": [
        {
          "exclusiveMinimum": 0,
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "page": {
      "const": 1
    },
    "page_token": {
      "default": "",
      "maxLength": 8192,
      "type": "string"
    },
    "query": {
      "anyOf": [
        {
          "maxLength": 200,
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "maxLength": 100
    },
    "search_mode": {
      "enum": [
        "text"
      ]
    },
    "source": {
      "const": "youtube"
    },
    "task_query": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Optional task attribution: when provided, write one concise, self-contained task_query in the user's language and reuse that exact value in every call for the task, including discovery, search, approval retry, results, export, and status checks. For MCP calls, when omitted, Asklear records a generic non-user-specific attribution so compatible clients can still call the tool. REST calls may omit it and remain unattributed. It is a task description, not a task identifier. Do not include hidden reasoning, credentials, or direct personal identifiers such as phone numbers, email addresses, identity numbers, or street addresses.",
      "maxLength": 300
    }
  },
  "required": [
    "source",
    "query"
  ],
  "type": "object"
}
```

### Synthetic request / 合成请求

```json
{
  "filters": {},
  "page": 1,
  "query": "示例关键词",
  "search_mode": "text",
  "source": "youtube"
}
```

### Synthetic response / 合成响应

```json
{
  "data": {
    "items": [],
    "pagination": {
      "has_more": false
    }
  }
}
```

- data.items (array<object>): Public Search results returned by this page.
- data.items[].entity_id (string): Stable public identifier for the result.
- data.items[].title (string|null): Public title when supplied.
- data.items[].url (string|null): Public result URL when supplied.
- data.items[].snippet (string|null): Source-independent text snippet when supplied.
- data.items[].video_id (string|null): Public video identifier.
- data.items[].summary (string|null): Public summary when supplied.
- data.items[].duration_text (string|null): Display duration text when supplied.
- data.items[].view_count (integer|null): View count.
- data.items[].view_count_text (string|null): Original view-count text when supplied.
- data.items[].published_at_text (string|null): Original publication-time text when supplied.
- data.items[].author_id (string|null): Author identifier.
- data.items[].author_name (string|null): Author display name.
- data.pagination.has_more (boolean): Whether another public Search page is available.
- data.pagination.next_page_token (string|null): Opaque continuation token for page_token; tokens start with asklear-search-cursor-v1.

Follow up: GET /v1/search/{job_id}
Read a pending search and its public results.