--- title: research youtube description: Research public YouTube videos and captions. canonical_url: https://orchestor.io/docs/en/cli/research/youtube markdown_url: https://orchestor.io/docs/en/cli/research/youtube.md contentType: reference --- # research youtube `orc research youtube` searches YouTube channels and videos and retrieves public information or captions. Filter video searches by publication time, duration or region, and retrieve captions for a batch of video IDs. Authenticate the CLI and select an accessible Workspace. Use `--workspace` to set the scope for this call. ## Usage ```bash title="terminal" orc research youtube videos search --query "生成AI" --workspace --json ``` *Search public videos.* ## Subcommands ### `channels get` Retrieve a channel using its UC-prefixed ID or handle without `@`, rather than a display name. ```bash title="terminal" orc research youtube channels get [options] ``` #### Unique options ##### `--channel-id` YouTube channel ID, starting with UC; not a display name. Type: `string`. Optional. ```bash title="terminal" orc research youtube channels get --channel-id ``` ##### `--handle` Channel handle without @.; max 100 chars Type: `string`. Optional. ```bash title="terminal" orc research youtube channels get --handle ``` ### `channels videos list` Read a channel’s public Videos tab, ordered by recency or popularity. `--include-extras true` requests additional publication and engagement data. ```bash title="terminal" orc research youtube channels videos list [options] ``` #### Unique options ##### `--channel-id` YouTube channel ID, starting with UC; not a display name. Type: `string`. Optional. ```bash title="terminal" orc research youtube channels videos list --channel-id ``` ##### `--handle` Channel handle without @.; max 100 chars Type: `string`. Optional. ```bash title="terminal" orc research youtube channels videos list --handle ``` ##### `--sort` Order the public Videos tab by recency or popularity. Omission sends no sort override.; enum: latest|popular Type: `string`. Optional. ```bash title="terminal" orc research youtube channels videos list --sort ``` ##### `--include-extras` Request enriched publication dates, descriptions and engagement with true. Send the literal query string true or false. Omission sends no extras override.; enum: true|false Type: `string`. Optional. ```bash title="terminal" orc research youtube channels videos list --include-extras ``` ### `channels search` Search channels using `--query` and follow returned cursors for continuation. ```bash title="terminal" orc research youtube channels search [options] ``` #### Unique options ##### `--query` Search text.; max 500 chars Type: `string`. Required. ```bash title="terminal" orc research youtube channels search --query ``` ### `videos search` Search videos by channel, publication time, duration, language, region and sort order. `--include-extras true` adds duration and engagement at five additional provider credits per page. ```bash title="terminal" orc research youtube videos search [options] ``` #### Unique options ##### `--query` Search text.; max 500 chars Type: `string`. Required. ```bash title="terminal" orc research youtube videos search --query ``` ##### `--channel-id` YouTube channel ID, starting with UC; not a display name. Type: `string`. Optional. ```bash title="terminal" orc research youtube videos search --channel-id ``` ##### `--published-after` Lower publication-time bound in ISO 8601 with a timezone. Must precede published_before when both are supplied. Omission adds no date cutoff. Type: `string`. Optional. ```bash title="terminal" orc research youtube videos search --published-after ``` ##### `--published-before` Upper publication-time bound in ISO 8601 with a timezone. Must follow published_after when both are supplied. Omission adds no upper date bound. Type: `string`. Optional. ```bash title="terminal" orc research youtube videos search --published-before ``` ##### `--order` Requested provider sort key. When omitted, Orchestor sends no order override.; enum: date|relevance|viewCount|rating|title Type: `string`. Optional. ```bash title="terminal" orc research youtube videos search --order ``` ##### `--max-results` Requested page size from 1 to 50. The provider may return fewer rows. Omission sends no page-size override. Type: `number`. Optional. ```bash title="terminal" orc research youtube videos search --max-results ``` ##### `--duration` Provider video-duration category. any requests no duration restriction; omission sends no override. Category boundaries are determined by the provider.; enum: short|medium|long|any Type: `string`. Optional. ```bash title="terminal" orc research youtube videos search --duration ``` ##### `--language` Two-letter preferred language. Caption behavior differs between single and batch endpoints. Type: `string`. Optional. ```bash title="terminal" orc research youtube videos search --language ``` ##### `--region` Two-uppercase-letter region code forwarded to the provider, for example JP or US. Omission sends no regional override. Type: `string`. Optional. ```bash title="terminal" orc research youtube videos search --region ``` ##### `--include-extras` Adds duration and engagement at an additional provider cost of 5 credits per page.; enum: true|false Type: `string`. Optional. ```bash title="terminal" orc research youtube videos search --include-extras ``` ### `transcripts get` Retrieve captions for one to twenty distinct video IDs supplied with `--ids`. `--export-format` selects caption representation; `--format` controls CLI output. ```bash title="terminal" orc research youtube transcripts get [options] ``` #### Unique options ##### `--export-format` Requested caption representation. Defaults to timed segments with millisecond timing; text requests combined caption text.; enum: text|segments Type: `string`. Optional. ```bash title="terminal" orc research youtube transcripts get --export-format ``` ##### `--ids` (required) One to twenty distinct video IDs. Correlate results using each row index and target.; csv Type: `string`. Optional. ```bash title="terminal" orc research youtube transcripts get --ids ``` ##### `--language` Two-letter preferred language. Caption behavior differs between single and batch endpoints. Type: `string`. Optional. ```bash title="terminal" orc research youtube transcripts get --language ``` ### `videos get` Retrieve video information from a public watch, Shorts, live or youtu.be URL. ```bash title="terminal" orc research youtube videos get [options] ``` #### Unique options ##### `--url` YouTube watch, Shorts, live or youtu.be URL.; max 2048 chars Type: `string`. Required. ```bash title="terminal" orc research youtube videos get --url ``` ##### `--language` Two-letter preferred language. Caption behavior differs between single and batch endpoints. Type: `string`. Optional. ```bash title="terminal" orc research youtube videos get --language ``` ### `videos transcript get` Retrieve captions from a public video URL without audio ASR or translation. ```bash title="terminal" orc research youtube videos transcript get [options] ``` #### Unique options ##### `--url` YouTube watch, Shorts, live or youtu.be URL.; max 2048 chars Type: `string`. Required. ```bash title="terminal" orc research youtube videos transcript get --url ``` ##### `--language` Two-letter preferred language. Caption behavior differs between single and batch endpoints. Type: `string`. Optional. ```bash title="terminal" orc research youtube videos transcript get --language ``` ## Examples ### Retrieve text captions for two videos. ```bash title="terminal" orc research youtube transcripts get --ids abcdefghijk,lmnopqrstuv --export-format text --workspace --json ``` *Retrieve text captions for two videos.* ## Output and continuation For lists with continuation, pass the API’s top-level `pagination.next_cursor` as `--cursor` with unchanged filters. In CLI JSON, extract `data.pagination.next_cursor`; do not replay a cursor nested inside source records. `has_more: null` means unknown rather than complete. `--page-all` is unavailable. With `--json`, the full API response is retained inside the CLI `data` envelope. Records are in `data.data`, continuation in `data.pagination`, and provenance in `data.source`. `--raw` removes the CLI envelope; `--field data` selects API data. Missing and null values do not mean zero. `data.usage.provider_credits` uses provider units, not Orchestor billing units. ## Caption acquisition and partial success `transcripts get` uses POST but requires read scope. Supply 1–20 distinct comma-separated video IDs with `--ids`. `--export-format text` selects caption representation; `--format json` selects CLI output. Segment timestamps use milliseconds. Acquisition covers public/manual and automatic captions, without audio ASR or translation. HTTP 200 may represent partial success: inspect every row status and summary, and avoid resubmitting successful rows. ## Permissions API keys require read scope. Provider credentials are managed by the server. ## Global Options The following [global options](https://orchestor.io/docs/cli/global-flags.md) can be used with `orc research youtube`: - [`--help`](https://orchestor.io/docs/cli/global-flags.md#help) - [`--workspace`](https://orchestor.io/docs/cli/global-flags.md#workspace) - [`--json`](https://orchestor.io/docs/cli/global-flags.md#json-output) - [`--pretty`](https://orchestor.io/docs/cli/global-flags.md#json-output) - [`--format`](https://orchestor.io/docs/cli/global-flags.md#output-format) - [`--field`](https://orchestor.io/docs/cli/global-flags.md#field-selection) - [`--fields`](https://orchestor.io/docs/cli/global-flags.md#field-selection) - [`--raw`](https://orchestor.io/docs/cli/global-flags.md#raw-output) - [`--output`](https://orchestor.io/docs/cli/global-flags.md#file-output) - [`--no-pager`](https://orchestor.io/docs/cli/global-flags.md#pager) - [`--dry-run`](https://orchestor.io/docs/cli/global-flags.md#dry-run) - [`--yes`](https://orchestor.io/docs/cli/global-flags.md#confirmation) - [`--cursor`](https://orchestor.io/docs/cli/global-flags.md) - [`--stdin`](https://orchestor.io/docs/cli/global-flags.md#standard-input) - [`--from-stdin`](https://orchestor.io/docs/cli/global-flags.md#standard-input) - [`--timing`](https://orchestor.io/docs/cli/global-flags.md#request-timing) For details and examples, see [global options](https://orchestor.io/docs/cli/global-flags.md). ## Related commands - Research overview - [Global options](https://orchestor.io/docs/en/cli/global-flags.md) --- [Documentation index](https://orchestor.io/docs/llms.txt)