​

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.

Search public videos.

Retrieve a channel using its UC-prefixed ID or handle without @, rather than a display name.

YouTube channel ID, starting with UC; not a display name.

Type: string. Optional.

Channel handle without @.; max 100 chars

Type: string. Optional.

Read a channel’s public Videos tab, ordered by recency or popularity. --include-extras true requests additional publication and engagement data.

YouTube channel ID, starting with UC; not a display name.

Type: string. Optional.

Channel handle without @.; max 100 chars

Type: string. Optional.

Order the public Videos tab by recency or popularity. Omission sends no sort override.; enum: latest|popular

Type: string. Optional.

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.

Search channels using --query and follow returned cursors for continuation.

Search text.; max 500 chars

Type: string. Required.

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.

Search text.; max 500 chars

Type: string. Required.

YouTube channel ID, starting with UC; not a display name.

Type: string. Optional.

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.

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.

Requested provider sort key. When omitted, Orchestor sends no order override.; enum: date|relevance|viewCount|rating|title

Type: string. Optional.

Requested page size from 1 to 50. The provider may return fewer rows. Omission sends no page-size override.

Type: number. Optional.

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.

Two-letter preferred language. Caption behavior differs between single and batch endpoints.

Type: string. Optional.

Two-uppercase-letter region code forwarded to the provider, for example JP or US. Omission sends no regional override.

Type: string. Optional.

Adds duration and engagement at an additional provider cost of 5 credits per page.; enum: true|false

Type: string. Optional.

Retrieve captions for one to twenty distinct video IDs supplied with --ids. --export-format selects caption representation; --format controls CLI output.

Requested caption representation. Defaults to timed segments with millisecond timing; text requests combined caption text.; enum: text|segments

Type: string. Optional.

(required) One to twenty distinct video IDs. Correlate results using each row index and target.; csv

Type: string. Optional.

Two-letter preferred language. Caption behavior differs between single and batch endpoints.

Type: string. Optional.

Retrieve video information from a public watch, Shorts, live or youtu.be URL.

YouTube watch, Shorts, live or youtu.be URL.; max 2048 chars

Type: string. Required.

Two-letter preferred language. Caption behavior differs between single and batch endpoints.

Type: string. Optional.

Retrieve captions from a public video URL without audio ASR or translation.

YouTube watch, Shorts, live or youtu.be URL.; max 2048 chars

Type: string. Required.

Two-letter preferred language. Caption behavior differs between single and batch endpoints.

Type: string. Optional.

Retrieve text captions for two videos.

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.

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.

API keys require read scope. Provider credentials are managed by the server.

The following global options can be used with orc research youtube:

For details and examples, see global options.