openapi: 3.2.0 info: title: Monocrawl YouTube API version: 0.1.0 description: One key, one envelope, one credit meter across social, search, commerce and web data. contact: name: Monocrawl support url: https://www.monocrawl.com/contact termsOfService: https://www.monocrawl.com/legal/terms-and-conditions servers: - url: https://www.monocrawl.com security: - ApiKeyHeader: [] tags: - name: Youtube paths: /v1/youtube/channel: get: operationId: youtube_channel tags: - Youtube summary: YouTube channel description: 'Channel profile: title, handle, subscriber/view/video counts, avatar, banner and the uploads playlist id. Costs 1 credit per successful live response.' parameters: - name: channelId in: query required: false schema: type: string example: UC_x5XG1OV2P6uZZ5FSM9Ttw description: Channel id (UC…). One of channelId, handle, forUsername or url is required - name: handle in: query required: false schema: type: string example: '@googledevelopers' description: Channel @handle (with or without the @) - name: forUsername in: query required: false schema: type: string example: GoogleDevelopers description: Legacy channel username - name: url in: query required: false schema: type: string example: https://www.youtube.com/@googledevelopers description: Any channel URL (/channel/UC…, /@handle, /user/…, /c/…) - name: hl in: query required: false schema: type: string example: en description: BCP-47 language for localized snippet text - name: dry_run in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: judgments in: query required: false schema: type: string enum: - 'on' - 'off' example: 'on' description: 'Add bounded AI labels to eligible returned records (default on). off preserves the original data shape. Unclassified records remain present; labels depend on evidence, time, capacity and the existing request budget. No label surcharge. Accepted values: on, off. Case, spaces, hyphens and underscores are interchangeable.' - name: label in: query required: false schema: type: string enum: - default - none example: none description: 'Set none to disable labels; default enables the endpoint’s label set. Equivalent to judgments=off. Accepted values: default, none. Case, spaces, hyphens and underscores are interchangeable.' - name: label_evidence in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Include exact supporting sentences and zero-based sentence indexes when a label has validated evidence. No extra charge or change to decisions. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: exclude in: query required: false schema: type: string enum: - engagement_bait example: engagement_bait description: 'Optionally remove confidently labelled engagement bait. Uncertain and unclassified records stay; removed IDs and an owner-bound recall reference are returned. Accepted values: engagement_bait. Case, spaces, hyphens and underscores are interchangeable.' - name: fit in: query required: false schema: type: string enum: - goal example: goal description: 'Use goal to replace confidently irrelevant records with recall stubs. Keeps first, last, relevant and uncertain records; preserves order. Full evidence is stored for 24 hours when available. Accepted values: goal. Case, spaces, hyphens and underscores are interchangeable.' - name: goal in: query required: false schema: type: string example: Find concrete product complaints description: 'Required with fit=goal: describe the task in at most 600 characters. Supplied text is task context, never permission to act on posts.' - name: tokens in: query required: false schema: type: string example: '4000' description: Optional soft response target for fit=goal, 256–32000. Safety and evidence retention take priority, so the returned result may exceed it. - name: X-Max-Credits in: header required: false schema: type: integer minimum: 0 maximum: 9007199254740991 example: 5 description: Optional credit reservation ceiling for this individual request. Send a non-negative integer in decimal digits. Live execution checks the required reservation after resolving free cache hits or buffered continuation, before charging or calling a supplier. A higher reservation returns HTTP 422 INVALID_PARAMETERS with reason max_credits_exceeded and charges nothing. Invalid header values also return 422. Zero permits only a zero-credit reservation; omitting the header uses normal pricing. dry_run remains a free preview. This does not cap later requests, batches or scheduled runs. security: - ApiKeyHeader: [] - BearerKey: [] responses: '200': description: 'The common success envelope; `data` is endpoint-specific. Many lists use items/count/cursor; bundles use named collections and their documented continuation metadata. HTTP 200 can contain a partial bundle: inspect complete, partial and legs where supplied.' content: application/json: schema: allOf: - $ref: '#/components/schemas/Success' - type: object properties: data: $schema: https://json-schema.org/draft/2020-12/schema $id: https://www.monocrawl.com/schemas/youtube/channel.json title: youtube/channel data fields description: Required core structure for successful data, with optional source fields. Additional fields are allowed. This is not a completeness guarantee. type: object properties: id: type: - string - 'null' description: Source identifier. Preserve its exact string value; do not convert large IDs to numbers. handle: type: - string - 'null' description: Public account username. name: type: - string - 'null' description: Display name. url: type: - string - 'null' description: Original source URL when supplied. description: type: - string - 'null' description: Channel description. country: type: - string - 'null' description: Channel country when supplied. subscribers: type: - number - 'null' description: Public subscribers; can be rounded reported by the source; null or absent is unknown, not zero. subscribers_hidden: type: - boolean - 'null' description: Whether the source marks subscriber totals hidden. views: type: - number - 'null' description: Channel views reported by the source; null or absent is unknown, not zero. video_count: type: - number - 'null' description: Videos reported by the source; null or absent is unknown, not zero. uploads_playlist_id: type: - string - 'null' description: Source identifier. Preserve its exact string value; do not convert large IDs to numbers. _warnings: type: array items: type: string description: Collection limitations or component warnings. Read before interpreting coverage. additionalProperties: true allOf: - anyOf: - required: - id properties: id: type: - string description: Source identifier. Preserve its exact string value; do not convert large IDs to numbers. minLength: 1 - required: - handle properties: handle: type: - string description: Public account username. minLength: 1 - required: - name properties: name: type: - string description: Display name. minLength: 1 - required: - url properties: url: type: - string description: Original source URL when supplied. minLength: 1 - required: - description properties: description: type: - string description: Channel description. minLength: 1 - required: - country properties: country: type: - string description: Channel country when supplied. minLength: 1 - required: - subscribers properties: subscribers: type: - number description: Public subscribers; can be rounded reported by the source; null or absent is unknown, not zero. - required: - subscribers_hidden properties: subscribers_hidden: type: - boolean description: Whether the source marks subscriber totals hidden. - required: - views properties: views: type: - number description: Channel views reported by the source; null or absent is unknown, not zero. - required: - video_count properties: video_count: type: - number description: Videos reported by the source; null or absent is unknown, not zero. - required: - uploads_playlist_id properties: uploads_playlist_id: type: - string description: Source identifier. Preserve its exact string value; do not convert large IDs to numbers. minLength: 1 x-contract-version: '2026-09-22' x-validation-scope: Required success payload structure; optional fields and source completeness remain separate. examples: - id: UC_example handle: '@example_channel' name: Example Channel subscribers: 12000 subscribers_hidden: false views: 840000 video_count: 96 default: description: The error envelope — the same shape for every non-2xx status. content: application/json: schema: $ref: '#/components/schemas/Error' x-credits: 1 x-production-available: true x-capacity: status: not_assessed message: Capacity is workload-dependent; configured routes do not establish sustained throughput or an availability guarantee. x-availability-scope: Structural check of the effective registered chain, production permission, adapter, configured cost and quality floor without request parameters. True is not a live-health, credential, quota, subscription-entitlement, complete-data or deployment-exposure guarantee. False means no structurally eligible candidate; null means metadata could not establish availability. Composite child capability still depends on its component routes. x-live-proven: true /v1/youtube/channel/playlists: get: operationId: youtube_channel_playlists tags: - Youtube summary: YouTube channel playlists description: 'Public playlists owned by a channel: title, description, item count and privacy. Costs 1 credit per successful live response.' parameters: - name: channelId in: query required: false schema: type: string example: UC_x5XG1OV2P6uZZ5FSM9Ttw description: Channel id. One of channelId, handle or url is required - name: handle in: query required: false schema: type: string example: '@googledevelopers' description: Channel @handle (resolved to a channel id first) - name: url in: query required: false schema: type: string example: https://www.youtube.com/@googledevelopers description: Any channel URL - name: max_results in: query required: false schema: type: string example: '50' description: Requested page size, 1–50. The paid primary defaults to 50; the source may return fewer. Keep an explicit size unchanged while paginating. - name: cursor in: query required: false schema: type: string example: CAUQAA description: Opaque page token from a previous response - name: dry_run in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: judgments in: query required: false schema: type: string enum: - 'on' - 'off' example: 'on' description: 'Add bounded AI labels to eligible returned records (default on). off preserves the original data shape. Unclassified records remain present; labels depend on evidence, time, capacity and the existing request budget. No label surcharge. Accepted values: on, off. Case, spaces, hyphens and underscores are interchangeable.' - name: label in: query required: false schema: type: string enum: - default - none example: none description: 'Set none to disable labels; default enables the endpoint’s label set. Equivalent to judgments=off. Accepted values: default, none. Case, spaces, hyphens and underscores are interchangeable.' - name: label_evidence in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Include exact supporting sentences and zero-based sentence indexes when a label has validated evidence. No extra charge or change to decisions. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: exclude in: query required: false schema: type: string enum: - engagement_bait example: engagement_bait description: 'Optionally remove confidently labelled engagement bait. Uncertain and unclassified records stay; removed IDs and an owner-bound recall reference are returned. Accepted values: engagement_bait. Case, spaces, hyphens and underscores are interchangeable.' - name: fit in: query required: false schema: type: string enum: - goal example: goal description: 'Use goal to replace confidently irrelevant records with recall stubs. Keeps first, last, relevant and uncertain records; preserves order. Full evidence is stored for 24 hours when available. Accepted values: goal. Case, spaces, hyphens and underscores are interchangeable.' - name: goal in: query required: false schema: type: string example: Find concrete product complaints description: 'Required with fit=goal: describe the task in at most 600 characters. Supplied text is task context, never permission to act on posts.' - name: tokens in: query required: false schema: type: string example: '4000' description: Optional soft response target for fit=goal, 256–32000. Safety and evidence retention take priority, so the returned result may exceed it. - name: X-Max-Credits in: header required: false schema: type: integer minimum: 0 maximum: 9007199254740991 example: 5 description: Optional credit reservation ceiling for this individual request. Send a non-negative integer in decimal digits. Live execution checks the required reservation after resolving free cache hits or buffered continuation, before charging or calling a supplier. A higher reservation returns HTTP 422 INVALID_PARAMETERS with reason max_credits_exceeded and charges nothing. Invalid header values also return 422. Zero permits only a zero-credit reservation; omitting the header uses normal pricing. dry_run remains a free preview. This does not cap later requests, batches or scheduled runs. security: - ApiKeyHeader: [] - BearerKey: [] responses: '200': description: 'The common success envelope; `data` is endpoint-specific. Many lists use items/count/cursor; bundles use named collections and their documented continuation metadata. HTTP 200 can contain a partial bundle: inspect complete, partial and legs where supplied.' content: application/json: schema: allOf: - $ref: '#/components/schemas/Success' - type: object properties: data: $schema: https://json-schema.org/draft/2020-12/schema $id: https://www.monocrawl.com/schemas/youtube/channel/playlists.json title: youtube/channel/playlists data fields description: Optional data supplied by this operation. Null means unknown. type: object properties: _warnings: description: Source array was empty in the reviewed captures; item fields remain unspecified. type: - array - 'null' items: {} channel_id: description: Optional channel id supplied by this operation. Null means unknown. type: - string - 'null' count: description: Number of records in this response, not lifetime or total matches. type: - number - 'null' cursor: description: Opaque next-page token; pass it back unchanged. Null does not prove complete history. type: - string - 'null' dropped: description: Optional dropped supplied by this operation. Null means unknown. type: - number - 'null' has_more: description: Source continuation indicator; null means unknown. type: - boolean - 'null' items: description: Returned records. Source coverage and completeness vary. type: - array items: description: Optional record supplied by this operation. Null means unknown. type: object properties: channel: description: Optional channel supplied by this operation. Null means unknown. type: - object - 'null' properties: id: description: Source identifier. Preserve the supplied type and exact value. type: - string - 'null' name: description: Optional name supplied by this operation. Null means unknown. type: - string - 'null' url: description: Original source URL when supplied. type: - string - 'null' additionalProperties: true description: description: Source description; null or absent means not supplied. type: - string - 'null' id: description: Source identifier. Preserve the supplied type and exact value. type: - string - 'null' privacy_status: description: Optional privacy status supplied by this operation. Null means unknown. type: - string - 'null' published_at: description: Source publication time when available. type: - string - 'null' thumbnails: description: Optional thumbnails supplied by this operation. Null means unknown. type: - object - 'null' properties: default: description: Optional default supplied by this operation. Null means unknown. type: - object - 'null' properties: {} additionalProperties: true fhd: description: Optional fhd supplied by this operation. Null means unknown. type: - object - 'null' properties: {} additionalProperties: true high: description: Optional high supplied by this operation. Null means unknown. type: - object - 'null' properties: {} additionalProperties: true maxres: description: Optional maxres supplied by this operation. Null means unknown. type: - object - 'null' properties: {} additionalProperties: true medium: description: Optional medium supplied by this operation. Null means unknown. type: - object - 'null' properties: {} additionalProperties: true standard: description: Optional standard supplied by this operation. Null means unknown. type: - object - 'null' properties: {} additionalProperties: true additionalProperties: true title: description: Source title when supplied. type: - string - 'null' url: description: Original source URL when supplied. type: - string - 'null' video_count: description: Optional video count supplied by this operation. Null means unknown. type: - number - 'null' additionalProperties: true allOf: - anyOf: - required: - channel properties: channel: description: Optional channel supplied by this operation. Null means unknown. type: - object properties: id: description: Source identifier. Preserve the supplied type and exact value. type: - string - 'null' name: description: Optional name supplied by this operation. Null means unknown. type: - string - 'null' url: description: Original source URL when supplied. type: - string - 'null' additionalProperties: true - required: - description properties: description: description: Source description; null or absent means not supplied. type: - string minLength: 1 - required: - id properties: id: description: Source identifier. Preserve the supplied type and exact value. type: - string minLength: 1 - required: - privacy_status properties: privacy_status: description: Optional privacy status supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - published_at properties: published_at: description: Source publication time when available. type: - string minLength: 1 - required: - thumbnails properties: thumbnails: description: Optional thumbnails supplied by this operation. Null means unknown. type: - object properties: default: description: Optional default supplied by this operation. Null means unknown. type: - object - 'null' properties: {} additionalProperties: true fhd: description: Optional fhd supplied by this operation. Null means unknown. type: - object - 'null' properties: {} additionalProperties: true high: description: Optional high supplied by this operation. Null means unknown. type: - object - 'null' properties: {} additionalProperties: true maxres: description: Optional maxres supplied by this operation. Null means unknown. type: - object - 'null' properties: {} additionalProperties: true medium: description: Optional medium supplied by this operation. Null means unknown. type: - object - 'null' properties: {} additionalProperties: true standard: description: Optional standard supplied by this operation. Null means unknown. type: - object - 'null' properties: {} additionalProperties: true additionalProperties: true - required: - title properties: title: description: Source title when supplied. type: - string minLength: 1 - required: - url properties: url: description: Original source URL when supplied. type: - string minLength: 1 - required: - video_count properties: video_count: description: Optional video count supplied by this operation. Null means unknown. type: - number total: description: Source-reported total; null is unknown. type: - number - 'null' additionalProperties: true required: - items x-contract-version: '2026-09-22' x-validation-scope: Required success payload structure; optional fields and source completeness remain separate. examples: - _warnings: [] channel_id: example count: 0 cursor: null dropped: 0 has_more: false items: - channel: id: example name: example url: https://example.com/example description: example id: example privacy_status: example published_at: '2026-09-01T12:00:00Z' thumbnails: default: {} fhd: {} high: {} maxres: {} medium: {} standard: {} title: example url: https://example.com/example video_count: 0 total: 0 default: description: The error envelope — the same shape for every non-2xx status. content: application/json: schema: $ref: '#/components/schemas/Error' x-credits: 1 x-production-available: true x-capacity: status: not_assessed message: Capacity is workload-dependent; configured routes do not establish sustained throughput or an availability guarantee. x-availability-scope: Structural check of the effective registered chain, production permission, adapter, configured cost and quality floor without request parameters. True is not a live-health, credential, quota, subscription-entitlement, complete-data or deployment-exposure guarantee. False means no structurally eligible candidate; null means metadata could not establish availability. Composite child capability still depends on its component routes. x-live-proven: true /v1/youtube/channel/videos: get: operationId: youtube_channel_videos tags: - Youtube summary: Channel uploads description: Retrieve videos from the channel uploads playlist in source order. This is an uploads-playlist collection, not every channel tab; popularity sorting is not supported. Costs 1 credit per successful live response. parameters: - name: channelId in: query required: false schema: type: string example: UC_x5XG1OV2P6uZZ5FSM9Ttw description: Channel id. One of channelId, handle or url is required - name: handle in: query required: false schema: type: string example: '@googledevelopers' description: Channel @handle - name: url in: query required: false schema: type: string example: https://www.youtube.com/@googledevelopers description: Any channel URL - name: max_results in: query required: false schema: type: string example: '50' description: Requested page size, 1–50. The paid primary defaults to 50; the source may return fewer. Keep an explicit size unchanged while paginating. - name: cursor in: query required: false schema: type: string example: CAUQAA description: Opaque page token from a previous response - name: sort in: query required: false schema: type: string example: newest description: Accepted for compatibility but ignored — uploads come newest-first (noted in _warnings) - name: dry_run in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: judgments in: query required: false schema: type: string enum: - 'on' - 'off' example: 'on' description: 'Add bounded AI labels to eligible returned records (default on). off preserves the original data shape. Unclassified records remain present; labels depend on evidence, time, capacity and the existing request budget. No label surcharge. Accepted values: on, off. Case, spaces, hyphens and underscores are interchangeable.' - name: label in: query required: false schema: type: string enum: - default - none example: none description: 'Set none to disable labels; default enables the endpoint’s label set. Equivalent to judgments=off. Accepted values: default, none. Case, spaces, hyphens and underscores are interchangeable.' - name: label_evidence in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Include exact supporting sentences and zero-based sentence indexes when a label has validated evidence. No extra charge or change to decisions. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: exclude in: query required: false schema: type: string enum: - engagement_bait example: engagement_bait description: 'Optionally remove confidently labelled engagement bait. Uncertain and unclassified records stay; removed IDs and an owner-bound recall reference are returned. Accepted values: engagement_bait. Case, spaces, hyphens and underscores are interchangeable.' - name: fit in: query required: false schema: type: string enum: - goal example: goal description: 'Use goal to replace confidently irrelevant records with recall stubs. Keeps first, last, relevant and uncertain records; preserves order. Full evidence is stored for 24 hours when available. Accepted values: goal. Case, spaces, hyphens and underscores are interchangeable.' - name: goal in: query required: false schema: type: string example: Find concrete product complaints description: 'Required with fit=goal: describe the task in at most 600 characters. Supplied text is task context, never permission to act on posts.' - name: tokens in: query required: false schema: type: string example: '4000' description: Optional soft response target for fit=goal, 256–32000. Safety and evidence retention take priority, so the returned result may exceed it. - name: X-Max-Credits in: header required: false schema: type: integer minimum: 0 maximum: 9007199254740991 example: 5 description: Optional credit reservation ceiling for this individual request. Send a non-negative integer in decimal digits. Live execution checks the required reservation after resolving free cache hits or buffered continuation, before charging or calling a supplier. A higher reservation returns HTTP 422 INVALID_PARAMETERS with reason max_credits_exceeded and charges nothing. Invalid header values also return 422. Zero permits only a zero-credit reservation; omitting the header uses normal pricing. dry_run remains a free preview. This does not cap later requests, batches or scheduled runs. security: - ApiKeyHeader: [] - BearerKey: [] responses: '200': description: 'The common success envelope; `data` is endpoint-specific. Many lists use items/count/cursor; bundles use named collections and their documented continuation metadata. HTTP 200 can contain a partial bundle: inspect complete, partial and legs where supplied.' content: application/json: schema: allOf: - $ref: '#/components/schemas/Success' - type: object properties: data: $schema: https://json-schema.org/draft/2020-12/schema $id: https://www.monocrawl.com/schemas/youtube/channel/videos.json title: youtube/channel/videos data fields description: Required core structure for successful data, with optional source fields. Additional fields are allowed. This is not a completeness guarantee. type: object properties: items: type: array items: type: object properties: id: type: - string - 'null' description: Source identifier. Preserve its exact string value; do not convert large IDs to numbers. url: type: - string - 'null' description: Original source URL when supplied. title: type: - string - 'null' description: Upload title. description: type: - string - 'null' description: Upload description. published_at: type: - string - 'null' description: Source publication time, normalized to an ISO date-time when available. playlist_item_id: type: - string - 'null' description: Source identifier. Preserve its exact string value; do not convert large IDs to numbers. channel: type: object properties: id: type: - string - 'null' description: Source identifier. Preserve its exact string value; do not convert large IDs to numbers. name: type: - string - 'null' description: Channel name. additionalProperties: true additionalProperties: true allOf: - anyOf: - required: - id properties: id: type: - string description: Source identifier. Preserve its exact string value; do not convert large IDs to numbers. minLength: 1 - required: - url properties: url: type: - string description: Original source URL when supplied. minLength: 1 - required: - title properties: title: type: - string description: Upload title. minLength: 1 - required: - description properties: description: type: - string description: Upload description. minLength: 1 - required: - published_at properties: published_at: type: - string description: Source publication time, normalized to an ISO date-time when available. minLength: 1 - required: - playlist_item_id properties: playlist_item_id: type: - string description: Source identifier. Preserve its exact string value; do not convert large IDs to numbers. minLength: 1 - required: - channel properties: channel: type: object properties: id: type: - string - 'null' description: Source identifier. Preserve its exact string value; do not convert large IDs to numbers. name: type: - string - 'null' description: Channel name. additionalProperties: true description: Records in this response page. count: type: - number - 'null' description: Returned row count when supplied; not the full source total. cursor: type: - string - 'null' description: Opaque next-page token. A missing token does not prove full history was retrieved. has_more: type: - boolean - 'null' description: Source continuation indicator; null means unknown. _warnings: type: array items: type: string description: Collection limitations or component warnings. Read before interpreting coverage. additionalProperties: true required: - items x-contract-version: '2026-09-22' x-validation-scope: Required success payload structure; optional fields and source completeness remain separate. examples: - items: - id: abcdefghijk url: https://www.youtube.com/watch?v=abcdefghijk title: A quieter desk setup published_at: '2026-09-01T12:00:00Z' cursor: null has_more: null default: description: The error envelope — the same shape for every non-2xx status. content: application/json: schema: $ref: '#/components/schemas/Error' x-credits: 1 x-production-available: true x-capacity: status: not_assessed message: Capacity is workload-dependent; configured routes do not establish sustained throughput or an availability guarantee. x-availability-scope: Structural check of the effective registered chain, production permission, adapter, configured cost and quality floor without request parameters. True is not a live-health, credential, quota, subscription-entitlement, complete-data or deployment-exposure guarantee. False means no structurally eligible candidate; null means metadata could not establish availability. Composite child capability still depends on its component routes. x-live-proven: true /v1/youtube/channels: get: operationId: youtube_channels tags: - Youtube summary: YouTube channels (batch) description: Batch channel lookup — one normalized record per id; unknown/terminated ids are reported in `missing`. Costs 2 credits per successful live response. parameters: - name: ids in: query required: true schema: type: string example: UC_x5XG1OV2P6uZZ5FSM9Ttw,UCrDkAvwZum-UTjHmzDI2iIw description: Comma-separated (or JSON array of) channel ids; up to 250, chunked 50 per upstream call - name: hl in: query required: false schema: type: string example: en description: BCP-47 language for localized snippet text - name: dry_run in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: X-Max-Credits in: header required: false schema: type: integer minimum: 0 maximum: 9007199254740991 example: 5 description: Optional credit reservation ceiling for this individual request. Send a non-negative integer in decimal digits. Live execution checks the required reservation after resolving free cache hits or buffered continuation, before charging or calling a supplier. A higher reservation returns HTTP 422 INVALID_PARAMETERS with reason max_credits_exceeded and charges nothing. Invalid header values also return 422. Zero permits only a zero-credit reservation; omitting the header uses normal pricing. dry_run remains a free preview. This does not cap later requests, batches or scheduled runs. security: - ApiKeyHeader: [] - BearerKey: [] responses: '200': description: 'The common success envelope; `data` is endpoint-specific. Many lists use items/count/cursor; bundles use named collections and their documented continuation metadata. HTTP 200 can contain a partial bundle: inspect complete, partial and legs where supplied.' content: application/json: schema: allOf: - $ref: '#/components/schemas/Success' - type: object properties: data: $schema: https://json-schema.org/draft/2020-12/schema $id: https://www.monocrawl.com/schemas/youtube/channels.json title: youtube/channels data fields description: Optional data supplied by this operation. Null means unknown. type: object properties: _warnings: description: Optional warnings supplied by this operation. Null means unknown. type: - array - 'null' items: description: Optional record supplied by this operation. Null means unknown. type: - string - 'null' count: description: Number of records in this response, not lifetime or total matches. type: - number - 'null' items: description: Returned records. Source coverage and completeness vary. type: - array items: description: Optional record supplied by this operation. Null means unknown. type: object properties: _warnings: description: Optional warnings supplied by this operation. Null means unknown. type: - array - 'null' items: description: Optional record supplied by this operation. Null means unknown. type: - string - 'null' avatar_url: description: Optional avatar url supplied by this operation. Null means unknown. type: - string - 'null' banner_url: description: Optional banner url supplied by this operation. Null means unknown. type: - string - 'null' country: description: Optional country supplied by this operation. Null means unknown. type: - string - 'null' description: description: Source description; null or absent means not supplied. type: - string - 'null' handle: description: Optional handle supplied by this operation. Null means unknown. type: - string - 'null' id: description: Source identifier. Preserve the supplied type and exact value. type: - string - 'null' keywords: description: Optional keywords supplied by this operation. Null means unknown. type: - string - 'null' name: description: Optional name supplied by this operation. Null means unknown. type: - string - 'null' published_at: description: Source publication time when available. type: - string - 'null' subscribers: description: Optional subscribers supplied by this operation. Null means unknown. type: - number - 'null' subscribers_hidden: description: Optional subscribers hidden supplied by this operation. Null means unknown. type: - boolean - 'null' thumbnails: description: Optional thumbnails supplied by this operation. Null means unknown. type: - object - 'null' properties: default: description: Optional default supplied by this operation. Null means unknown. type: - object - 'null' properties: {} additionalProperties: true high: description: Optional high supplied by this operation. Null means unknown. type: - object - 'null' properties: {} additionalProperties: true medium: description: Optional medium supplied by this operation. Null means unknown. type: - object - 'null' properties: {} additionalProperties: true additionalProperties: true uploads_playlist_id: description: Optional uploads playlist id supplied by this operation. Null means unknown. type: - string - 'null' url: description: Original source URL when supplied. type: - string - 'null' video_count: description: Optional video count supplied by this operation. Null means unknown. type: - number - 'null' views: description: Optional views supplied by this operation. Null means unknown. type: - number - 'null' additionalProperties: true allOf: - anyOf: - required: - avatar_url properties: avatar_url: description: Optional avatar url supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - banner_url properties: banner_url: description: Optional banner url supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - country properties: country: description: Optional country supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - description properties: description: description: Source description; null or absent means not supplied. type: - string minLength: 1 - required: - handle properties: handle: description: Optional handle supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - id properties: id: description: Source identifier. Preserve the supplied type and exact value. type: - string minLength: 1 - required: - keywords properties: keywords: description: Optional keywords supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - name properties: name: description: Optional name supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - published_at properties: published_at: description: Source publication time when available. type: - string minLength: 1 - required: - subscribers properties: subscribers: description: Optional subscribers supplied by this operation. Null means unknown. type: - number - required: - subscribers_hidden properties: subscribers_hidden: description: Optional subscribers hidden supplied by this operation. Null means unknown. type: - boolean - required: - thumbnails properties: thumbnails: description: Optional thumbnails supplied by this operation. Null means unknown. type: - object properties: default: description: Optional default supplied by this operation. Null means unknown. type: - object - 'null' properties: {} additionalProperties: true high: description: Optional high supplied by this operation. Null means unknown. type: - object - 'null' properties: {} additionalProperties: true medium: description: Optional medium supplied by this operation. Null means unknown. type: - object - 'null' properties: {} additionalProperties: true additionalProperties: true - required: - uploads_playlist_id properties: uploads_playlist_id: description: Optional uploads playlist id supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - url properties: url: description: Original source URL when supplied. type: - string minLength: 1 - required: - video_count properties: video_count: description: Optional video count supplied by this operation. Null means unknown. type: - number - required: - views properties: views: description: Optional views supplied by this operation. Null means unknown. type: - number missing: description: Source array was empty in the reviewed captures; item fields remain unspecified. type: - array - 'null' items: {} requested: description: Optional requested supplied by this operation. Null means unknown. type: - number - 'null' additionalProperties: true required: - items x-contract-version: '2026-09-22' x-validation-scope: Required success payload structure; optional fields and source completeness remain separate. examples: - _warnings: - example count: 0 items: - _warnings: - example avatar_url: https://example.com/example banner_url: https://example.com/example country: example description: example handle: example id: example keywords: example name: example published_at: '2026-09-01T12:00:00Z' subscribers: 0 subscribers_hidden: false thumbnails: default: {} high: {} medium: {} uploads_playlist_id: example url: https://example.com/example video_count: 0 views: 0 missing: [] requested: 0 default: description: The error envelope — the same shape for every non-2xx status. content: application/json: schema: $ref: '#/components/schemas/Error' x-credits: 2 x-production-available: true x-capacity: status: not_assessed message: Capacity is workload-dependent; configured routes do not establish sustained throughput or an availability guarantee. x-availability-scope: Structural check of the effective registered chain, production permission, adapter, configured cost and quality floor without request parameters. True is not a live-health, credential, quota, subscription-entitlement, complete-data or deployment-exposure guarantee. False means no structurally eligible candidate; null means metadata could not establish availability. Composite child capability still depends on its component routes. x-live-proven: true /v1/youtube/community-post: get: operationId: youtube_community_post tags: - Youtube summary: Community post description: One community post by URL. Costs 2 credits per successful live response. parameters: - name: url in: query required: true schema: type: string example: https://www.youtube.com/post/UgkxzJ6r7VLAK03TN5Gjq7YpjHmjtee_Rdn9 description: Full community post URL. - name: dry_run in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: judgments in: query required: false schema: type: string enum: - 'on' - 'off' example: 'on' description: 'Add bounded AI labels to eligible returned records (default on). off preserves the original data shape. Unclassified records remain present; labels depend on evidence, time, capacity and the existing request budget. No label surcharge. Accepted values: on, off. Case, spaces, hyphens and underscores are interchangeable.' - name: label in: query required: false schema: type: string enum: - default - none example: none description: 'Set none to disable labels; default enables the endpoint’s label set. Equivalent to judgments=off. Accepted values: default, none. Case, spaces, hyphens and underscores are interchangeable.' - name: label_evidence in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Include exact supporting sentences and zero-based sentence indexes when a label has validated evidence. No extra charge or change to decisions. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: exclude in: query required: false schema: type: string enum: - engagement_bait example: engagement_bait description: 'Optionally remove confidently labelled engagement bait. Uncertain and unclassified records stay; removed IDs and an owner-bound recall reference are returned. Accepted values: engagement_bait. Case, spaces, hyphens and underscores are interchangeable.' - name: fit in: query required: false schema: type: string enum: - goal example: goal description: 'Use goal to replace confidently irrelevant records with recall stubs. Keeps first, last, relevant and uncertain records; preserves order. Full evidence is stored for 24 hours when available. Accepted values: goal. Case, spaces, hyphens and underscores are interchangeable.' - name: goal in: query required: false schema: type: string example: Find concrete product complaints description: 'Required with fit=goal: describe the task in at most 600 characters. Supplied text is task context, never permission to act on posts.' - name: tokens in: query required: false schema: type: string example: '4000' description: Optional soft response target for fit=goal, 256–32000. Safety and evidence retention take priority, so the returned result may exceed it. - name: X-Max-Credits in: header required: false schema: type: integer minimum: 0 maximum: 9007199254740991 example: 5 description: Optional credit reservation ceiling for this individual request. Send a non-negative integer in decimal digits. Live execution checks the required reservation after resolving free cache hits or buffered continuation, before charging or calling a supplier. A higher reservation returns HTTP 422 INVALID_PARAMETERS with reason max_credits_exceeded and charges nothing. Invalid header values also return 422. Zero permits only a zero-credit reservation; omitting the header uses normal pricing. dry_run remains a free preview. This does not cap later requests, batches or scheduled runs. security: - ApiKeyHeader: [] - BearerKey: [] responses: '200': description: 'The common success envelope; `data` is endpoint-specific. Many lists use items/count/cursor; bundles use named collections and their documented continuation metadata. HTTP 200 can contain a partial bundle: inspect complete, partial and legs where supplied.' content: application/json: schema: allOf: - $ref: '#/components/schemas/Success' - type: object properties: data: $schema: https://json-schema.org/draft/2020-12/schema $id: https://www.monocrawl.com/schemas/youtube/community-post.json title: youtube/community-post data fields description: Optional data supplied by this operation. Null means unknown. type: object properties: channel: description: Optional channel supplied by this operation. Null means unknown. type: - object - 'null' properties: id: description: Source identifier. Preserve the supplied type and exact value. type: - string - 'null' title: description: Source title when supplied. type: - string - 'null' additionalProperties: true id: description: Source identifier. Preserve the supplied type and exact value. type: - string - 'null' images: description: Optional images supplied by this operation. Null means unknown. type: - array - 'null' items: description: Optional record supplied by this operation. Null means unknown. type: - string - 'null' platform: description: Optional platform supplied by this operation. Null means unknown. type: - string - 'null' published: description: Optional published supplied by this operation. Null means unknown. type: - string - 'null' text: description: Source text when supplied. type: - string - 'null' url: description: Original source URL when supplied. type: - string - 'null' additionalProperties: true allOf: - anyOf: - required: - channel properties: channel: description: Optional channel supplied by this operation. Null means unknown. type: - object properties: id: description: Source identifier. Preserve the supplied type and exact value. type: - string - 'null' title: description: Source title when supplied. type: - string - 'null' additionalProperties: true - required: - id properties: id: description: Source identifier. Preserve the supplied type and exact value. type: - string minLength: 1 - required: - images properties: images: description: Optional images supplied by this operation. Null means unknown. type: - array items: description: Optional record supplied by this operation. Null means unknown. type: - string - 'null' - required: - published properties: published: description: Optional published supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - text properties: text: description: Source text when supplied. type: - string minLength: 1 - required: - url properties: url: description: Original source URL when supplied. type: - string minLength: 1 x-contract-version: '2026-09-22' x-validation-scope: Required success payload structure; optional fields and source completeness remain separate. examples: - channel: id: example title: example id: example images: - example platform: example published: example text: example url: https://example.com/example default: description: The error envelope — the same shape for every non-2xx status. content: application/json: schema: $ref: '#/components/schemas/Error' x-credits: 2 x-production-available: true x-capacity: status: not_assessed message: Capacity is workload-dependent; configured routes do not establish sustained throughput or an availability guarantee. x-availability-scope: Structural check of the effective registered chain, production permission, adapter, configured cost and quality floor without request parameters. True is not a live-health, credential, quota, subscription-entitlement, complete-data or deployment-exposure guarantee. False means no structurally eligible candidate; null means metadata could not establish availability. Composite child capability still depends on its component routes. x-live-proven: true /v1/youtube/community-posts: get: operationId: youtube_community_posts tags: - Youtube summary: Community posts description: 'A channel''s community-tab posts: text, images, likes and attached videos. Paged by cursor. Costs 2 credits per successful live response.' parameters: - name: handle in: query required: true schema: type: string example: MrBeast description: Channel handle without the @ (or pass channelId). - name: channelId in: query required: false schema: type: string description: Channel id — alternative to handle. - name: cursor in: query required: false schema: type: string description: continuationToken from the previous page. - name: dry_run in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: judgments in: query required: false schema: type: string enum: - 'on' - 'off' example: 'on' description: 'Add bounded AI labels to eligible returned records (default on). off preserves the original data shape. Unclassified records remain present; labels depend on evidence, time, capacity and the existing request budget. No label surcharge. Accepted values: on, off. Case, spaces, hyphens and underscores are interchangeable.' - name: label in: query required: false schema: type: string enum: - default - none example: none description: 'Set none to disable labels; default enables the endpoint’s label set. Equivalent to judgments=off. Accepted values: default, none. Case, spaces, hyphens and underscores are interchangeable.' - name: label_evidence in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Include exact supporting sentences and zero-based sentence indexes when a label has validated evidence. No extra charge or change to decisions. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: exclude in: query required: false schema: type: string enum: - engagement_bait example: engagement_bait description: 'Optionally remove confidently labelled engagement bait. Uncertain and unclassified records stay; removed IDs and an owner-bound recall reference are returned. Accepted values: engagement_bait. Case, spaces, hyphens and underscores are interchangeable.' - name: fit in: query required: false schema: type: string enum: - goal example: goal description: 'Use goal to replace confidently irrelevant records with recall stubs. Keeps first, last, relevant and uncertain records; preserves order. Full evidence is stored for 24 hours when available. Accepted values: goal. Case, spaces, hyphens and underscores are interchangeable.' - name: goal in: query required: false schema: type: string example: Find concrete product complaints description: 'Required with fit=goal: describe the task in at most 600 characters. Supplied text is task context, never permission to act on posts.' - name: tokens in: query required: false schema: type: string example: '4000' description: Optional soft response target for fit=goal, 256–32000. Safety and evidence retention take priority, so the returned result may exceed it. - name: X-Max-Credits in: header required: false schema: type: integer minimum: 0 maximum: 9007199254740991 example: 5 description: Optional credit reservation ceiling for this individual request. Send a non-negative integer in decimal digits. Live execution checks the required reservation after resolving free cache hits or buffered continuation, before charging or calling a supplier. A higher reservation returns HTTP 422 INVALID_PARAMETERS with reason max_credits_exceeded and charges nothing. Invalid header values also return 422. Zero permits only a zero-credit reservation; omitting the header uses normal pricing. dry_run remains a free preview. This does not cap later requests, batches or scheduled runs. security: - ApiKeyHeader: [] - BearerKey: [] responses: '200': description: 'The common success envelope; `data` is endpoint-specific. Many lists use items/count/cursor; bundles use named collections and their documented continuation metadata. HTTP 200 can contain a partial bundle: inspect complete, partial and legs where supplied.' content: application/json: schema: allOf: - $ref: '#/components/schemas/Success' - type: object properties: data: $schema: https://json-schema.org/draft/2020-12/schema $id: https://www.monocrawl.com/schemas/youtube/community-posts.json title: youtube/community-posts data fields description: Optional data supplied by this operation. Null means unknown. type: object properties: cursor: description: Opaque next-page token; pass it back unchanged. Null does not prove complete history. type: - string - 'null' dropped: description: Optional dropped supplied by this operation. Null means unknown. type: - number - 'null' items: description: Returned records. Source coverage and completeness vary. type: - array items: description: Optional record supplied by this operation. Null means unknown. type: object properties: channel: description: Optional channel supplied by this operation. Null means unknown. type: - object - 'null' properties: id: description: Source identifier. Preserve the supplied type and exact value. type: - string - 'null' title: description: Source title when supplied. type: - string - 'null' additionalProperties: true id: description: Source identifier. Preserve the supplied type and exact value. type: - string - 'null' images: description: Optional images supplied by this operation. Null means unknown. type: - array - 'null' items: description: Optional record supplied by this operation. Null means unknown. type: - string - 'null' platform: description: Optional platform supplied by this operation. Null means unknown. type: - string - 'null' published: description: Optional published supplied by this operation. Null means unknown. type: - string - 'null' text: description: Source text when supplied. type: - string - 'null' url: description: Original source URL when supplied. type: - string - 'null' additionalProperties: true allOf: - anyOf: - required: - channel properties: channel: description: Optional channel supplied by this operation. Null means unknown. type: - object properties: id: description: Source identifier. Preserve the supplied type and exact value. type: - string - 'null' title: description: Source title when supplied. type: - string - 'null' additionalProperties: true - required: - id properties: id: description: Source identifier. Preserve the supplied type and exact value. type: - string minLength: 1 - required: - images properties: images: description: Optional images supplied by this operation. Null means unknown. type: - array items: description: Optional record supplied by this operation. Null means unknown. type: - string - 'null' - required: - published properties: published: description: Optional published supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - text properties: text: description: Source text when supplied. type: - string minLength: 1 - required: - url properties: url: description: Original source URL when supplied. type: - string minLength: 1 additionalProperties: true required: - items x-contract-version: '2026-09-22' x-validation-scope: Required success payload structure; optional fields and source completeness remain separate. examples: - cursor: null dropped: 0 items: - channel: id: example title: example id: example images: - example platform: example published: example text: example url: https://example.com/example default: description: The error envelope — the same shape for every non-2xx status. content: application/json: schema: $ref: '#/components/schemas/Error' x-credits: 2 x-production-available: true x-capacity: status: not_assessed message: Capacity is workload-dependent; configured routes do not establish sustained throughput or an availability guarantee. x-availability-scope: Structural check of the effective registered chain, production permission, adapter, configured cost and quality floor without request parameters. True is not a live-health, credential, quota, subscription-entitlement, complete-data or deployment-exposure guarantee. False means no structurally eligible candidate; null means metadata could not establish availability. Composite child capability still depends on its component routes. x-live-proven: true /v1/youtube/lives: get: operationId: youtube_lives tags: - Youtube summary: Channel live streams description: 'A channel''s live tab: current and past streams with view counts and live state. Paged by cursor. Costs 2 credits per successful live response.' parameters: - name: handle in: query required: true schema: type: string example: IShowSpeed description: Channel handle without the @ (or pass channelId). - name: channelId in: query required: false schema: type: string description: Channel id — alternative to handle. - name: cursor in: query required: false schema: type: string description: continuationToken from the previous page. - name: dry_run in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: X-Max-Credits in: header required: false schema: type: integer minimum: 0 maximum: 9007199254740991 example: 5 description: Optional credit reservation ceiling for this individual request. Send a non-negative integer in decimal digits. Live execution checks the required reservation after resolving free cache hits or buffered continuation, before charging or calling a supplier. A higher reservation returns HTTP 422 INVALID_PARAMETERS with reason max_credits_exceeded and charges nothing. Invalid header values also return 422. Zero permits only a zero-credit reservation; omitting the header uses normal pricing. dry_run remains a free preview. This does not cap later requests, batches or scheduled runs. security: - ApiKeyHeader: [] - BearerKey: [] responses: '200': description: 'The common success envelope; `data` is endpoint-specific. Many lists use items/count/cursor; bundles use named collections and their documented continuation metadata. HTTP 200 can contain a partial bundle: inspect complete, partial and legs where supplied.' content: application/json: schema: allOf: - $ref: '#/components/schemas/Success' - type: object properties: data: $schema: https://json-schema.org/draft/2020-12/schema $id: https://www.monocrawl.com/schemas/youtube/lives.json title: youtube/lives data fields description: Optional data supplied by this operation. Null means unknown. type: object properties: cursor: description: Opaque next-page token; pass it back unchanged. Null does not prove complete history. type: - string - 'null' dropped: description: Optional dropped supplied by this operation. Null means unknown. type: - number - 'null' items: description: Returned records. Source coverage and completeness vary. type: - array items: description: Optional record supplied by this operation. Null means unknown. type: object properties: id: description: Source identifier. Preserve the supplied type and exact value. type: - string - 'null' is_live: description: Optional is live supplied by this operation. Null means unknown. type: - boolean - 'null' platform: description: Optional platform supplied by this operation. Null means unknown. type: - string - 'null' published: description: Optional published supplied by this operation. Null means unknown. type: - string - 'null' thumbnail: description: Optional thumbnail supplied by this operation. Null means unknown. type: - string - 'null' title: description: Source title when supplied. type: - string - 'null' url: description: Original source URL when supplied. type: - string - 'null' viewers: description: Optional viewers supplied by this operation. Null means unknown. type: - number - 'null' additionalProperties: true allOf: - anyOf: - required: - id properties: id: description: Source identifier. Preserve the supplied type and exact value. type: - string minLength: 1 - required: - is_live properties: is_live: description: Optional is live supplied by this operation. Null means unknown. type: - boolean - required: - published properties: published: description: Optional published supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - thumbnail properties: thumbnail: description: Optional thumbnail supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - title properties: title: description: Source title when supplied. type: - string minLength: 1 - required: - url properties: url: description: Original source URL when supplied. type: - string minLength: 1 - required: - viewers properties: viewers: description: Optional viewers supplied by this operation. Null means unknown. type: - number additionalProperties: true required: - items x-contract-version: '2026-09-22' x-validation-scope: Required success payload structure; optional fields and source completeness remain separate. examples: - cursor: null dropped: 0 items: - id: example is_live: false platform: example published: example thumbnail: example title: example url: https://example.com/example viewers: 0 default: description: The error envelope — the same shape for every non-2xx status. content: application/json: schema: $ref: '#/components/schemas/Error' x-credits: 2 x-production-available: true x-capacity: status: not_assessed message: Capacity is workload-dependent; configured routes do not establish sustained throughput or an availability guarantee. x-availability-scope: Structural check of the effective registered chain, production permission, adapter, configured cost and quality floor without request parameters. True is not a live-health, credential, quota, subscription-entitlement, complete-data or deployment-exposure guarantee. False means no structurally eligible candidate; null means metadata could not establish availability. Composite child capability still depends on its component routes. x-live-proven: true /v1/youtube/playlist: get: operationId: youtube_playlist tags: - Youtube summary: YouTube playlist description: 'Playlist metadata: title, description, owning channel, video count and privacy. Costs 1 credit per successful live response.' parameters: - name: playlist_id in: query required: true schema: type: string example: PLOU2XLYxmsIKpaV8h0AGE05so0fAwwfTw description: Playlist id - name: dry_run in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: X-Max-Credits in: header required: false schema: type: integer minimum: 0 maximum: 9007199254740991 example: 5 description: Optional credit reservation ceiling for this individual request. Send a non-negative integer in decimal digits. Live execution checks the required reservation after resolving free cache hits or buffered continuation, before charging or calling a supplier. A higher reservation returns HTTP 422 INVALID_PARAMETERS with reason max_credits_exceeded and charges nothing. Invalid header values also return 422. Zero permits only a zero-credit reservation; omitting the header uses normal pricing. dry_run remains a free preview. This does not cap later requests, batches or scheduled runs. security: - ApiKeyHeader: [] - BearerKey: [] responses: '200': description: 'The common success envelope; `data` is endpoint-specific. Many lists use items/count/cursor; bundles use named collections and their documented continuation metadata. HTTP 200 can contain a partial bundle: inspect complete, partial and legs where supplied.' content: application/json: schema: allOf: - $ref: '#/components/schemas/Success' - type: object properties: data: $schema: https://json-schema.org/draft/2020-12/schema $id: https://www.monocrawl.com/schemas/youtube/playlist.json title: youtube/playlist data fields description: Optional data supplied by this operation. Null means unknown. type: object properties: channel: description: Optional channel supplied by this operation. Null means unknown. type: - object - 'null' properties: id: description: Source identifier. Preserve the supplied type and exact value. type: - string - 'null' name: description: Optional name supplied by this operation. Null means unknown. type: - string - 'null' url: description: Original source URL when supplied. type: - string - 'null' additionalProperties: true description: description: Source description; null or absent means not supplied. type: - string - 'null' id: description: Source identifier. Preserve the supplied type and exact value. type: - string - 'null' privacy_status: description: Optional privacy status supplied by this operation. Null means unknown. type: - string - 'null' published_at: description: Source publication time when available. type: - string - 'null' thumbnails: description: Optional thumbnails supplied by this operation. Null means unknown. type: - object - 'null' properties: default: description: Optional default supplied by this operation. Null means unknown. type: - object - 'null' properties: height: description: Optional height supplied by this operation. Null means unknown. type: - number - 'null' url: description: Original source URL when supplied. type: - string - 'null' width: description: Optional width supplied by this operation. Null means unknown. type: - number - 'null' additionalProperties: true high: description: Optional high supplied by this operation. Null means unknown. type: - object - 'null' properties: height: description: Optional height supplied by this operation. Null means unknown. type: - number - 'null' url: description: Original source URL when supplied. type: - string - 'null' width: description: Optional width supplied by this operation. Null means unknown. type: - number - 'null' additionalProperties: true maxres: description: Optional maxres supplied by this operation. Null means unknown. type: - object - 'null' properties: height: description: Optional height supplied by this operation. Null means unknown. type: - number - 'null' url: description: Original source URL when supplied. type: - string - 'null' width: description: Optional width supplied by this operation. Null means unknown. type: - number - 'null' additionalProperties: true medium: description: Optional medium supplied by this operation. Null means unknown. type: - object - 'null' properties: height: description: Optional height supplied by this operation. Null means unknown. type: - number - 'null' url: description: Original source URL when supplied. type: - string - 'null' width: description: Optional width supplied by this operation. Null means unknown. type: - number - 'null' additionalProperties: true standard: description: Optional standard supplied by this operation. Null means unknown. type: - object - 'null' properties: height: description: Optional height supplied by this operation. Null means unknown. type: - number - 'null' url: description: Original source URL when supplied. type: - string - 'null' width: description: Optional width supplied by this operation. Null means unknown. type: - number - 'null' additionalProperties: true additionalProperties: true title: description: Source title when supplied. type: - string - 'null' url: description: Original source URL when supplied. type: - string - 'null' video_count: description: Optional video count supplied by this operation. Null means unknown. type: - number - 'null' additionalProperties: true allOf: - anyOf: - required: - channel properties: channel: description: Optional channel supplied by this operation. Null means unknown. type: - object properties: id: description: Source identifier. Preserve the supplied type and exact value. type: - string - 'null' name: description: Optional name supplied by this operation. Null means unknown. type: - string - 'null' url: description: Original source URL when supplied. type: - string - 'null' additionalProperties: true - required: - description properties: description: description: Source description; null or absent means not supplied. type: - string minLength: 1 - required: - id properties: id: description: Source identifier. Preserve the supplied type and exact value. type: - string minLength: 1 - required: - privacy_status properties: privacy_status: description: Optional privacy status supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - published_at properties: published_at: description: Source publication time when available. type: - string minLength: 1 - required: - thumbnails properties: thumbnails: description: Optional thumbnails supplied by this operation. Null means unknown. type: - object properties: default: description: Optional default supplied by this operation. Null means unknown. type: - object - 'null' properties: height: description: Optional height supplied by this operation. Null means unknown. type: - number - 'null' url: description: Original source URL when supplied. type: - string - 'null' width: description: Optional width supplied by this operation. Null means unknown. type: - number - 'null' additionalProperties: true high: description: Optional high supplied by this operation. Null means unknown. type: - object - 'null' properties: height: description: Optional height supplied by this operation. Null means unknown. type: - number - 'null' url: description: Original source URL when supplied. type: - string - 'null' width: description: Optional width supplied by this operation. Null means unknown. type: - number - 'null' additionalProperties: true maxres: description: Optional maxres supplied by this operation. Null means unknown. type: - object - 'null' properties: height: description: Optional height supplied by this operation. Null means unknown. type: - number - 'null' url: description: Original source URL when supplied. type: - string - 'null' width: description: Optional width supplied by this operation. Null means unknown. type: - number - 'null' additionalProperties: true medium: description: Optional medium supplied by this operation. Null means unknown. type: - object - 'null' properties: height: description: Optional height supplied by this operation. Null means unknown. type: - number - 'null' url: description: Original source URL when supplied. type: - string - 'null' width: description: Optional width supplied by this operation. Null means unknown. type: - number - 'null' additionalProperties: true standard: description: Optional standard supplied by this operation. Null means unknown. type: - object - 'null' properties: height: description: Optional height supplied by this operation. Null means unknown. type: - number - 'null' url: description: Original source URL when supplied. type: - string - 'null' width: description: Optional width supplied by this operation. Null means unknown. type: - number - 'null' additionalProperties: true additionalProperties: true - required: - title properties: title: description: Source title when supplied. type: - string minLength: 1 - required: - url properties: url: description: Original source URL when supplied. type: - string minLength: 1 - required: - video_count properties: video_count: description: Optional video count supplied by this operation. Null means unknown. type: - number x-contract-version: '2026-09-22' x-validation-scope: Required success payload structure; optional fields and source completeness remain separate. examples: - channel: id: example name: example url: https://example.com/example description: example id: example privacy_status: example published_at: '2026-09-01T12:00:00Z' thumbnails: default: height: 0 url: https://example.com/example width: 0 high: height: 0 url: https://example.com/example width: 0 maxres: height: 0 url: https://example.com/example width: 0 medium: height: 0 url: https://example.com/example width: 0 standard: height: 0 url: https://example.com/example width: 0 title: example url: https://example.com/example video_count: 0 default: description: The error envelope — the same shape for every non-2xx status. content: application/json: schema: $ref: '#/components/schemas/Error' x-credits: 1 x-production-available: true x-capacity: status: not_assessed message: Capacity is workload-dependent; configured routes do not establish sustained throughput or an availability guarantee. x-availability-scope: Structural check of the effective registered chain, production permission, adapter, configured cost and quality floor without request parameters. True is not a live-health, credential, quota, subscription-entitlement, complete-data or deployment-exposure guarantee. False means no structurally eligible candidate; null means metadata could not establish availability. Composite child capability still depends on its component routes. x-live-proven: true /v1/youtube/playlist/items: get: operationId: youtube_playlist_items tags: - Youtube summary: YouTube playlist items description: The videos in a playlist, in playlist order, with per-item position and dates. Costs 1 credit per successful live response. parameters: - name: playlist_id in: query required: true schema: type: string example: PLOU2XLYxmsIKpaV8h0AGE05so0fAwwfTw description: Playlist id - name: max_results in: query required: false schema: type: string example: '50' description: Requested page size, 1–50. The paid primary defaults to 50; the source may return fewer. Keep an explicit size unchanged while paginating. - name: cursor in: query required: false schema: type: string example: CAUQAA description: Opaque page token from a previous response - name: dry_run in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: X-Max-Credits in: header required: false schema: type: integer minimum: 0 maximum: 9007199254740991 example: 5 description: Optional credit reservation ceiling for this individual request. Send a non-negative integer in decimal digits. Live execution checks the required reservation after resolving free cache hits or buffered continuation, before charging or calling a supplier. A higher reservation returns HTTP 422 INVALID_PARAMETERS with reason max_credits_exceeded and charges nothing. Invalid header values also return 422. Zero permits only a zero-credit reservation; omitting the header uses normal pricing. dry_run remains a free preview. This does not cap later requests, batches or scheduled runs. security: - ApiKeyHeader: [] - BearerKey: [] responses: '200': description: 'The common success envelope; `data` is endpoint-specific. Many lists use items/count/cursor; bundles use named collections and their documented continuation metadata. HTTP 200 can contain a partial bundle: inspect complete, partial and legs where supplied.' content: application/json: schema: allOf: - $ref: '#/components/schemas/Success' - type: object properties: data: $schema: https://json-schema.org/draft/2020-12/schema $id: https://www.monocrawl.com/schemas/youtube/playlist/items.json title: youtube/playlist/items data fields description: Optional data supplied by this operation. Null means unknown. type: object properties: _warnings: description: Source array was empty in the reviewed captures; item fields remain unspecified. type: - array - 'null' items: {} count: description: Number of records in this response, not lifetime or total matches. type: - number - 'null' dropped: description: Optional dropped supplied by this operation. Null means unknown. type: - number - 'null' has_more: description: Source continuation indicator; null means unknown. type: - boolean - 'null' items: description: Returned records. Source coverage and completeness vary. type: - array items: description: Optional record supplied by this operation. Null means unknown. type: object properties: added_to_playlist_at: description: Optional added to playlist at supplied by this operation. Null means unknown. type: - string - 'null' channel: description: Optional channel supplied by this operation. Null means unknown. type: - object - 'null' properties: id: description: Source identifier. Preserve the supplied type and exact value. type: - string - 'null' name: description: Optional name supplied by this operation. Null means unknown. type: - string - 'null' additionalProperties: true description: description: Source description; null or absent means not supplied. type: - string - 'null' id: description: Source identifier. Preserve the supplied type and exact value. type: - string - 'null' playlist_item_id: description: Optional playlist item id supplied by this operation. Null means unknown. type: - string - 'null' position: description: Optional position supplied by this operation. Null means unknown. type: - number - 'null' published_at: description: Source publication time when available. type: - string - 'null' thumbnails: description: Optional thumbnails supplied by this operation. Null means unknown. type: - object - 'null' properties: default: description: Optional default supplied by this operation. Null means unknown. type: - object - 'null' properties: {} additionalProperties: true high: description: Optional high supplied by this operation. Null means unknown. type: - object - 'null' properties: {} additionalProperties: true maxres: description: Optional maxres supplied by this operation. Null means unknown. type: - object - 'null' properties: {} additionalProperties: true medium: description: Optional medium supplied by this operation. Null means unknown. type: - object - 'null' properties: {} additionalProperties: true standard: description: Optional standard supplied by this operation. Null means unknown. type: - object - 'null' properties: {} additionalProperties: true additionalProperties: true title: description: Source title when supplied. type: - string - 'null' url: description: Original source URL when supplied. type: - string - 'null' additionalProperties: true allOf: - anyOf: - required: - added_to_playlist_at properties: added_to_playlist_at: description: Optional added to playlist at supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - channel properties: channel: description: Optional channel supplied by this operation. Null means unknown. type: - object properties: id: description: Source identifier. Preserve the supplied type and exact value. type: - string - 'null' name: description: Optional name supplied by this operation. Null means unknown. type: - string - 'null' additionalProperties: true - required: - description properties: description: description: Source description; null or absent means not supplied. type: - string minLength: 1 - required: - id properties: id: description: Source identifier. Preserve the supplied type and exact value. type: - string minLength: 1 - required: - playlist_item_id properties: playlist_item_id: description: Optional playlist item id supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - position properties: position: description: Optional position supplied by this operation. Null means unknown. type: - number - required: - published_at properties: published_at: description: Source publication time when available. type: - string minLength: 1 - required: - thumbnails properties: thumbnails: description: Optional thumbnails supplied by this operation. Null means unknown. type: - object properties: default: description: Optional default supplied by this operation. Null means unknown. type: - object - 'null' properties: {} additionalProperties: true high: description: Optional high supplied by this operation. Null means unknown. type: - object - 'null' properties: {} additionalProperties: true maxres: description: Optional maxres supplied by this operation. Null means unknown. type: - object - 'null' properties: {} additionalProperties: true medium: description: Optional medium supplied by this operation. Null means unknown. type: - object - 'null' properties: {} additionalProperties: true standard: description: Optional standard supplied by this operation. Null means unknown. type: - object - 'null' properties: {} additionalProperties: true additionalProperties: true - required: - title properties: title: description: Source title when supplied. type: - string minLength: 1 - required: - url properties: url: description: Original source URL when supplied. type: - string minLength: 1 playlist_id: description: Optional playlist id supplied by this operation. Null means unknown. type: - string - 'null' total: description: Source-reported total; null is unknown. type: - number - 'null' additionalProperties: true required: - items x-contract-version: '2026-09-22' x-validation-scope: Required success payload structure; optional fields and source completeness remain separate. examples: - _warnings: [] count: 0 dropped: 0 has_more: false items: - added_to_playlist_at: '2026-09-01T12:00:00Z' channel: id: example name: example description: example id: example playlist_item_id: example position: 0 published_at: '2026-09-01T12:00:00Z' thumbnails: default: {} high: {} maxres: {} medium: {} standard: {} title: example url: https://example.com/example playlist_id: example total: 0 default: description: The error envelope — the same shape for every non-2xx status. content: application/json: schema: $ref: '#/components/schemas/Error' x-credits: 1 x-production-available: true x-capacity: status: not_assessed message: Capacity is workload-dependent; configured routes do not establish sustained throughput or an availability guarantee. x-availability-scope: Structural check of the effective registered chain, production permission, adapter, configured cost and quality floor without request parameters. True is not a live-health, credential, quota, subscription-entitlement, complete-data or deployment-exposure guarantee. False means no structurally eligible candidate; null means metadata could not establish availability. Composite child capability still depends on its component routes. x-live-proven: true /v1/youtube/post-transcript: get: operationId: youtube_post_transcript tags: - Youtube summary: Video transcript description: The spoken words of a YouTube video as timestamped segments plus plain text. transcript is null when the video has no captions. Costs 2 credits per successful live response. parameters: - name: url in: query required: true schema: type: string example: https://www.youtube.com/watch?v=jNQXAC9IVRw description: Full YouTube video URL. - name: dry_run in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: X-Max-Credits in: header required: false schema: type: integer minimum: 0 maximum: 9007199254740991 example: 5 description: Optional credit reservation ceiling for this individual request. Send a non-negative integer in decimal digits. Live execution checks the required reservation after resolving free cache hits or buffered continuation, before charging or calling a supplier. A higher reservation returns HTTP 422 INVALID_PARAMETERS with reason max_credits_exceeded and charges nothing. Invalid header values also return 422. Zero permits only a zero-credit reservation; omitting the header uses normal pricing. dry_run remains a free preview. This does not cap later requests, batches or scheduled runs. security: - ApiKeyHeader: [] - BearerKey: [] responses: '200': description: 'The common success envelope; `data` is endpoint-specific. Many lists use items/count/cursor; bundles use named collections and their documented continuation metadata. HTTP 200 can contain a partial bundle: inspect complete, partial and legs where supplied.' content: application/json: schema: allOf: - $ref: '#/components/schemas/Success' - type: object properties: data: $schema: https://json-schema.org/draft/2020-12/schema $id: https://www.monocrawl.com/schemas/youtube/post-transcript.json title: youtube/post-transcript data fields description: Optional data supplied by this operation. Null means unknown. type: object properties: has_transcript: description: Optional has transcript supplied by this operation. Null means unknown. type: - boolean - 'null' language: description: Optional language supplied by this operation. Null means unknown. type: - string - 'null' platform: description: Optional platform supplied by this operation. Null means unknown. type: - string - 'null' segments: description: Optional segments supplied by this operation. Null means unknown. type: - array - 'null' items: description: Optional record supplied by this operation. Null means unknown. type: - object - 'null' properties: end_ms: description: Optional end ms supplied by this operation. Null means unknown. type: - number - 'null' start_ms: description: Optional start ms supplied by this operation. Null means unknown. type: - number - 'null' text: description: Source text when supplied. type: - string - 'null' additionalProperties: true transcript: description: Optional transcript supplied by this operation. Null means unknown. type: - string - 'null' url: description: Original source URL when supplied. type: - string - 'null' video_id: description: Optional video id supplied by this operation. Null means unknown. type: - string - 'null' additionalProperties: true allOf: - anyOf: - required: - has_transcript properties: has_transcript: description: Optional has transcript supplied by this operation. Null means unknown. type: - boolean - required: - language properties: language: description: Optional language supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - segments properties: segments: description: Optional segments supplied by this operation. Null means unknown. type: - array items: description: Optional record supplied by this operation. Null means unknown. type: - object - 'null' properties: end_ms: description: Optional end ms supplied by this operation. Null means unknown. type: - number - 'null' start_ms: description: Optional start ms supplied by this operation. Null means unknown. type: - number - 'null' text: description: Source text when supplied. type: - string - 'null' additionalProperties: true - required: - transcript properties: transcript: description: Optional transcript supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - url properties: url: description: Original source URL when supplied. type: - string minLength: 1 - required: - video_id properties: video_id: description: Optional video id supplied by this operation. Null means unknown. type: - string minLength: 1 x-contract-version: '2026-09-22' x-validation-scope: Required success payload structure; optional fields and source completeness remain separate. examples: - has_transcript: false language: example platform: example segments: - end_ms: 0 start_ms: 0 text: example transcript: example url: https://example.com/example video_id: example default: description: The error envelope — the same shape for every non-2xx status. content: application/json: schema: $ref: '#/components/schemas/Error' x-credits: 2 x-production-available: true x-capacity: status: not_assessed message: Capacity is workload-dependent; configured routes do not establish sustained throughput or an availability guarantee. x-availability-scope: Structural check of the effective registered chain, production permission, adapter, configured cost and quality floor without request parameters. True is not a live-health, credential, quota, subscription-entitlement, complete-data or deployment-exposure guarantee. False means no structurally eligible candidate; null means metadata could not establish availability. Composite child capability still depends on its component routes. x-live-proven: true /v1/youtube/profile: get: operationId: youtube_profile tags: - Youtube summary: YouTube channel profile description: 'Public YouTube channel: identity, description, subscriber/video/view counts. Costs 1 credit per successful live response.' parameters: - name: handle in: query required: true schema: type: string example: '@NASA' description: Channel handle, e.g. @NASA. - name: dry_run in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: judgments in: query required: false schema: type: string enum: - 'on' - 'off' example: 'on' description: 'Add bounded AI labels to eligible returned records (default on). off preserves the original data shape. Unclassified records remain present; labels depend on evidence, time, capacity and the existing request budget. No label surcharge. Accepted values: on, off. Case, spaces, hyphens and underscores are interchangeable.' - name: label in: query required: false schema: type: string enum: - default - none example: none description: 'Set none to disable labels; default enables the endpoint’s label set. Equivalent to judgments=off. Accepted values: default, none. Case, spaces, hyphens and underscores are interchangeable.' - name: label_evidence in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Include exact supporting sentences and zero-based sentence indexes when a label has validated evidence. No extra charge or change to decisions. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: exclude in: query required: false schema: type: string enum: - engagement_bait example: engagement_bait description: 'Optionally remove confidently labelled engagement bait. Uncertain and unclassified records stay; removed IDs and an owner-bound recall reference are returned. Accepted values: engagement_bait. Case, spaces, hyphens and underscores are interchangeable.' - name: fit in: query required: false schema: type: string enum: - goal example: goal description: 'Use goal to replace confidently irrelevant records with recall stubs. Keeps first, last, relevant and uncertain records; preserves order. Full evidence is stored for 24 hours when available. Accepted values: goal. Case, spaces, hyphens and underscores are interchangeable.' - name: goal in: query required: false schema: type: string example: Find concrete product complaints description: 'Required with fit=goal: describe the task in at most 600 characters. Supplied text is task context, never permission to act on posts.' - name: tokens in: query required: false schema: type: string example: '4000' description: Optional soft response target for fit=goal, 256–32000. Safety and evidence retention take priority, so the returned result may exceed it. - name: X-Max-Credits in: header required: false schema: type: integer minimum: 0 maximum: 9007199254740991 example: 5 description: Optional credit reservation ceiling for this individual request. Send a non-negative integer in decimal digits. Live execution checks the required reservation after resolving free cache hits or buffered continuation, before charging or calling a supplier. A higher reservation returns HTTP 422 INVALID_PARAMETERS with reason max_credits_exceeded and charges nothing. Invalid header values also return 422. Zero permits only a zero-credit reservation; omitting the header uses normal pricing. dry_run remains a free preview. This does not cap later requests, batches or scheduled runs. security: - ApiKeyHeader: [] - BearerKey: [] responses: '200': description: 'The common success envelope; `data` is endpoint-specific. Many lists use items/count/cursor; bundles use named collections and their documented continuation metadata. HTTP 200 can contain a partial bundle: inspect complete, partial and legs where supplied.' content: application/json: schema: allOf: - $ref: '#/components/schemas/Success' - type: object properties: data: $schema: https://json-schema.org/draft/2020-12/schema $id: https://www.monocrawl.com/schemas/youtube/profile.json title: youtube/profile data fields description: Required core structure for successful data, with optional source fields. Additional fields are allowed. This is not a completeness guarantee. type: object properties: id: type: - string - 'null' description: Source identifier. Preserve its exact string value; do not convert large IDs to numbers. handle: type: - string - 'null' description: Public account username. name: type: - string - 'null' description: Display name. url: type: - string - 'null' description: Original source URL when supplied. bio: type: - string - 'null' description: Public biography. bio_link: type: - string - 'null' description: Original source URL when supplied. avatar_url: type: - string - 'null' description: Original source URL when supplied. followers: type: - number - 'null' description: Followers reported by the source; null or absent is unknown, not zero. following: type: - number - 'null' description: Following reported by the source; null or absent is unknown, not zero. verified: type: - boolean - 'null' description: Source verification flag; meaning depends on the platform. banner_url: type: - string - 'null' description: Original source URL when supplied. video_count: type: - number - 'null' description: Videos reported by the source; null or absent is unknown, not zero. view_count: type: - number - 'null' description: Channel views reported by the source; null or absent is unknown, not zero. joined_text: type: - string - 'null' description: Source join-date text; may be approximate. family_safe: type: - boolean - 'null' description: Source family-safe flag. country: type: - string - 'null' description: Public channel country. links: type: - array - 'null' items: type: string description: Public external HTTP(S) links supplied by the profile source; null is unknown. _warnings: type: array items: type: string description: Collection limitations or component warnings. Read before interpreting coverage. additionalProperties: true allOf: - anyOf: - required: - id properties: id: type: - string description: Source identifier. Preserve its exact string value; do not convert large IDs to numbers. minLength: 1 - required: - handle properties: handle: type: - string description: Public account username. minLength: 1 - required: - name properties: name: type: - string description: Display name. minLength: 1 - required: - url properties: url: type: - string description: Original source URL when supplied. minLength: 1 - required: - bio properties: bio: type: - string description: Public biography. minLength: 1 - required: - bio_link properties: bio_link: type: - string description: Original source URL when supplied. minLength: 1 - required: - avatar_url properties: avatar_url: type: - string description: Original source URL when supplied. minLength: 1 - required: - followers properties: followers: type: - number description: Followers reported by the source; null or absent is unknown, not zero. - required: - following properties: following: type: - number description: Following reported by the source; null or absent is unknown, not zero. - required: - verified properties: verified: type: - boolean description: Source verification flag; meaning depends on the platform. - required: - banner_url properties: banner_url: type: - string description: Original source URL when supplied. minLength: 1 - required: - video_count properties: video_count: type: - number description: Videos reported by the source; null or absent is unknown, not zero. - required: - view_count properties: view_count: type: - number description: Channel views reported by the source; null or absent is unknown, not zero. - required: - joined_text properties: joined_text: type: - string description: Source join-date text; may be approximate. minLength: 1 - required: - family_safe properties: family_safe: type: - boolean description: Source family-safe flag. - required: - country properties: country: type: - string description: Public channel country. minLength: 1 - required: - links properties: links: type: - array items: type: string description: Public external HTTP(S) links supplied by the profile source; null is unknown. x-contract-version: '2026-09-22' x-validation-scope: Required success payload structure; optional fields and source completeness remain separate. examples: - id: '7350000000000000001' handle: example_creator name: Example Creator followers: 12000 following: 180 bio: null verified: false links: - https://example.com country: null default: description: The error envelope — the same shape for every non-2xx status. content: application/json: schema: $ref: '#/components/schemas/Error' x-credits: 1 x-production-available: true x-capacity: status: not_assessed message: Capacity is workload-dependent; configured routes do not establish sustained throughput or an availability guarantee. x-availability-scope: Structural check of the effective registered chain, production permission, adapter, configured cost and quality floor without request parameters. True is not a live-health, credential, quota, subscription-entitlement, complete-data or deployment-exposure guarantee. False means no structurally eligible candidate; null means metadata could not establish availability. Composite child capability still depends on its component routes. x-live-proven: true /v1/youtube/profile/full: get: operationId: youtube_profile_full tags: - Youtube summary: YouTube profile (full) description: 'One-call channel dossier: channel profile, recent uploads with stats, and computed engagement analytics; per-source failures reported inline. Costs 5 credits per successful live response.' parameters: - name: channelId in: query required: false schema: type: string example: UC_x5XG1OV2P6uZZ5FSM9Ttw description: Channel id. One of channelId, handle or url is required - name: handle in: query required: false schema: type: string example: '@googledevelopers' description: Channel @handle - name: url in: query required: false schema: type: string example: https://www.youtube.com/@googledevelopers description: Any channel URL - name: posts in: query required: false schema: type: string example: '10' description: Recent uploads to sample for analytics, 1-50 (default 10) - name: cursor in: query required: false schema: type: string example: CAUQAA description: Opaque page token to continue the recent-uploads listing - name: include in: query required: false schema: type: string example: videos,analytics description: 'Comma list: videos and/or analytics (default both)' - name: dry_run in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: judgments in: query required: false schema: type: string enum: - 'on' - 'off' example: 'on' description: 'Add bounded AI labels to eligible returned records (default on). off preserves the original data shape. Unclassified records remain present; labels depend on evidence, time, capacity and the existing request budget. No label surcharge. Accepted values: on, off. Case, spaces, hyphens and underscores are interchangeable.' - name: label in: query required: false schema: type: string enum: - default - none example: none description: 'Set none to disable labels; default enables the endpoint’s label set. Equivalent to judgments=off. Accepted values: default, none. Case, spaces, hyphens and underscores are interchangeable.' - name: label_evidence in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Include exact supporting sentences and zero-based sentence indexes when a label has validated evidence. No extra charge or change to decisions. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: exclude in: query required: false schema: type: string enum: - engagement_bait example: engagement_bait description: 'Optionally remove confidently labelled engagement bait. Uncertain and unclassified records stay; removed IDs and an owner-bound recall reference are returned. Accepted values: engagement_bait. Case, spaces, hyphens and underscores are interchangeable.' - name: fit in: query required: false schema: type: string enum: - goal example: goal description: 'Use goal to replace confidently irrelevant records with recall stubs. Keeps first, last, relevant and uncertain records; preserves order. Full evidence is stored for 24 hours when available. Accepted values: goal. Case, spaces, hyphens and underscores are interchangeable.' - name: goal in: query required: false schema: type: string example: Find concrete product complaints description: 'Required with fit=goal: describe the task in at most 600 characters. Supplied text is task context, never permission to act on posts.' - name: tokens in: query required: false schema: type: string example: '4000' description: Optional soft response target for fit=goal, 256–32000. Safety and evidence retention take priority, so the returned result may exceed it. - name: X-Max-Credits in: header required: false schema: type: integer minimum: 0 maximum: 9007199254740991 example: 5 description: Optional credit reservation ceiling for this individual request. Send a non-negative integer in decimal digits. Live execution checks the required reservation after resolving free cache hits or buffered continuation, before charging or calling a supplier. A higher reservation returns HTTP 422 INVALID_PARAMETERS with reason max_credits_exceeded and charges nothing. Invalid header values also return 422. Zero permits only a zero-credit reservation; omitting the header uses normal pricing. dry_run remains a free preview. This does not cap later requests, batches or scheduled runs. security: - ApiKeyHeader: [] - BearerKey: [] responses: '200': description: 'The common success envelope; `data` is endpoint-specific. Many lists use items/count/cursor; bundles use named collections and their documented continuation metadata. HTTP 200 can contain a partial bundle: inspect complete, partial and legs where supplied.' content: application/json: schema: allOf: - $ref: '#/components/schemas/Success' - type: object properties: data: $schema: https://json-schema.org/draft/2020-12/schema $id: https://www.monocrawl.com/schemas/youtube/profile/full.json title: youtube/profile/full data fields description: Required core structure for successful data, with optional source fields. Additional fields are allowed. This is not a completeness guarantee. type: object properties: channel: type: object properties: id: type: - string - 'null' description: Source identifier. Preserve its exact string value; do not convert large IDs to numbers. handle: type: - string - 'null' description: Public account username. name: type: - string - 'null' description: Display name. url: type: - string - 'null' description: Original source URL when supplied. description: type: - string - 'null' description: Channel description. country: type: - string - 'null' description: Channel country when supplied. subscribers: type: - number - 'null' description: Public subscribers; can be rounded reported by the source; null or absent is unknown, not zero. subscribers_hidden: type: - boolean - 'null' description: Whether the source marks subscriber totals hidden. views: type: - number - 'null' description: Channel views reported by the source; null or absent is unknown, not zero. video_count: type: - number - 'null' description: Videos reported by the source; null or absent is unknown, not zero. uploads_playlist_id: type: - string - 'null' description: Source identifier. Preserve its exact string value; do not convert large IDs to numbers. additionalProperties: true recent_videos: type: array items: type: object properties: id: type: - string - 'null' description: Source identifier. Preserve its exact string value; do not convert large IDs to numbers. url: type: - string - 'null' description: Original source URL when supplied. title: type: - string - 'null' description: Video title. description: type: - string - 'null' description: Video description. published_at: type: - string - 'null' description: Source publication time, normalized to an ISO date-time when available. duration_seconds: type: - number - 'null' description: Duration in seconds. channel: type: object properties: id: type: - string - 'null' description: Source identifier. Preserve its exact string value; do not convert large IDs to numbers. name: type: - string - 'null' description: Channel display name. url: type: - string - 'null' description: Original source URL when supplied. additionalProperties: true views: type: - number - 'null' description: Views reported by the source; null or absent is unknown, not zero. likes: type: - number - 'null' description: Likes reported by the source; null or absent is unknown, not zero. comments_count: type: - number - 'null' description: Comments reported by the source; null or absent is unknown, not zero. additionalProperties: true recent_count: type: - number - 'null' description: Returned uploads reported by the source; null or absent is unknown, not zero. cursor: type: - string - 'null' description: Uploads continuation token. recent_videos_pagination: type: object properties: returned: type: - number - 'null' description: Returned uploads reported by the source; null or absent is unknown, not zero. total: type: - number - 'null' description: Reported uploads reported by the source; null or absent is unknown, not zero. has_more: type: - boolean - 'null' description: Whether another source page is reported. additionalProperties: true sources: type: array items: type: object properties: source: type: - string - 'null' description: Component name. ok: type: - boolean - 'null' description: Component request success. complete: type: - boolean - 'null' description: All requested detail records returned. missing_ids: type: array items: type: string additionalProperties: true analytics: type: - object - 'null' properties: sampled_videos: type: - number - 'null' description: Videos with numeric view counts reported by the source; null or absent is unknown, not zero. metric_samples: type: object properties: views: type: - number - 'null' description: Videos with views reported by the source; null or absent is unknown, not zero. likes: type: - number - 'null' description: View-sample videos with likes reported by the source; null or absent is unknown, not zero. comments: type: - number - 'null' description: View-sample videos with comments reported by the source; null or absent is unknown, not zero. engagement: type: - number - 'null' description: Videos with all three counters reported by the source; null or absent is unknown, not zero. additionalProperties: true avg_views: type: - number - 'null' description: Rounded average views over the view sample. avg_likes: type: - number - 'null' description: Rounded average likes over available values in the view sample. avg_comments: type: - number - 'null' description: Rounded average comments over available values in the view sample. engagement_rate: type: - number - 'null' description: (sum likes + sum comments) / sum views for complete triples, rounded to six decimals. A ratio, not percent; null with zero summed views. most_viewed_video_id: type: - string - 'null' description: Source identifier. Preserve its exact string value; do not convert large IDs to numbers. additionalProperties: true _warnings: type: array items: type: string description: Collection limitations or component warnings. Read before interpreting coverage. additionalProperties: true allOf: - anyOf: - required: - channel properties: channel: type: object properties: id: type: - string - 'null' description: Source identifier. Preserve its exact string value; do not convert large IDs to numbers. handle: type: - string - 'null' description: Public account username. name: type: - string - 'null' description: Display name. url: type: - string - 'null' description: Original source URL when supplied. description: type: - string - 'null' description: Channel description. country: type: - string - 'null' description: Channel country when supplied. subscribers: type: - number - 'null' description: Public subscribers; can be rounded reported by the source; null or absent is unknown, not zero. subscribers_hidden: type: - boolean - 'null' description: Whether the source marks subscriber totals hidden. views: type: - number - 'null' description: Channel views reported by the source; null or absent is unknown, not zero. video_count: type: - number - 'null' description: Videos reported by the source; null or absent is unknown, not zero. uploads_playlist_id: type: - string - 'null' description: Source identifier. Preserve its exact string value; do not convert large IDs to numbers. additionalProperties: true - required: - recent_videos properties: recent_videos: type: array items: type: object properties: id: type: - string - 'null' description: Source identifier. Preserve its exact string value; do not convert large IDs to numbers. url: type: - string - 'null' description: Original source URL when supplied. title: type: - string - 'null' description: Video title. description: type: - string - 'null' description: Video description. published_at: type: - string - 'null' description: Source publication time, normalized to an ISO date-time when available. duration_seconds: type: - number - 'null' description: Duration in seconds. channel: type: object properties: id: type: - string - 'null' description: Source identifier. Preserve its exact string value; do not convert large IDs to numbers. name: type: - string - 'null' description: Channel display name. url: type: - string - 'null' description: Original source URL when supplied. additionalProperties: true views: type: - number - 'null' description: Views reported by the source; null or absent is unknown, not zero. likes: type: - number - 'null' description: Likes reported by the source; null or absent is unknown, not zero. comments_count: type: - number - 'null' description: Comments reported by the source; null or absent is unknown, not zero. additionalProperties: true - required: - recent_count properties: recent_count: type: - number description: Returned uploads reported by the source; null or absent is unknown, not zero. - required: - recent_videos_pagination properties: recent_videos_pagination: type: object properties: returned: type: - number - 'null' description: Returned uploads reported by the source; null or absent is unknown, not zero. total: type: - number - 'null' description: Reported uploads reported by the source; null or absent is unknown, not zero. has_more: type: - boolean - 'null' description: Whether another source page is reported. additionalProperties: true - required: - sources properties: sources: type: array items: type: object properties: source: type: - string - 'null' description: Component name. ok: type: - boolean - 'null' description: Component request success. complete: type: - boolean - 'null' description: All requested detail records returned. missing_ids: type: array items: type: string additionalProperties: true - required: - analytics properties: analytics: type: - object properties: sampled_videos: type: - number - 'null' description: Videos with numeric view counts reported by the source; null or absent is unknown, not zero. metric_samples: type: object properties: views: type: - number - 'null' description: Videos with views reported by the source; null or absent is unknown, not zero. likes: type: - number - 'null' description: View-sample videos with likes reported by the source; null or absent is unknown, not zero. comments: type: - number - 'null' description: View-sample videos with comments reported by the source; null or absent is unknown, not zero. engagement: type: - number - 'null' description: Videos with all three counters reported by the source; null or absent is unknown, not zero. additionalProperties: true avg_views: type: - number - 'null' description: Rounded average views over the view sample. avg_likes: type: - number - 'null' description: Rounded average likes over available values in the view sample. avg_comments: type: - number - 'null' description: Rounded average comments over available values in the view sample. engagement_rate: type: - number - 'null' description: (sum likes + sum comments) / sum views for complete triples, rounded to six decimals. A ratio, not percent; null with zero summed views. most_viewed_video_id: type: - string - 'null' description: Source identifier. Preserve its exact string value; do not convert large IDs to numbers. additionalProperties: true x-contract-version: '2026-09-22' x-validation-scope: Required success payload structure; optional fields and source completeness remain separate. examples: - channel: id: UC_example name: Example Channel recent_videos: - id: abcdefghijk title: A quieter desk setup published_at: '2026-09-01T12:00:00Z' channel: id: UC_example name: Example Channel duration_seconds: 482 views: 12600 likes: 640 comments_count: 38 recent_count: 1 cursor: null recent_videos_pagination: returned: 1 total: null has_more: false default: description: The error envelope — the same shape for every non-2xx status. content: application/json: schema: $ref: '#/components/schemas/Error' x-credits: 5 x-production-available: true x-capacity: status: not_assessed message: Capacity is workload-dependent; configured routes do not establish sustained throughput or an availability guarantee. x-availability-scope: Structural check of the effective registered chain, production permission, adapter, configured cost and quality floor without request parameters. True is not a live-health, credential, quota, subscription-entitlement, complete-data or deployment-exposure guarantee. False means no structurally eligible candidate; null means metadata could not establish availability. Composite child capability still depends on its component routes. x-live-proven: true /v1/youtube/search: get: operationId: youtube_search tags: - Youtube summary: YouTube search description: Search YouTube for videos, channels and playlists (Data API search.list; 100 quota units per call). Costs 1 credit per successful live response. parameters: - name: query in: query required: true schema: type: string example: lofi hip hop description: Search query - name: type in: query required: false schema: type: array items: type: string enum: - video - channel - playlist style: form explode: false example: - video description: 'Result kinds: video, channel, playlist (comma-separable) Accepted values (comma-separated): video, channel, playlist. Case, spaces, hyphens and underscores are interchangeable.' - name: sortBy in: query required: false schema: type: string enum: - relevance - date - rating - title - views - viewCount - viewcount example: date description: 'relevance, date, rating, title or views (maps to order/viewCount) Accepted values: relevance, date, rating, title, views, viewCount, viewcount. Case, spaces, hyphens and underscores are interchangeable.' - name: duration in: query required: false schema: type: string enum: - short - medium - long example: medium description: 'short, medium or long (forces video results) Accepted values: short, medium, long. Case, spaces, hyphens and underscores are interchangeable.' - name: uploadDate in: query required: false schema: type: string enum: - hour - lasthour - today - day - week - thisweek - month - thismonth - year - thisyear example: week description: 'hour/today/week/month/year — mapped to publishedAfter Accepted values: hour, lasthour, today, day, week, thisweek, month, thismonth, year, thisyear. Case, spaces, hyphens and underscores are interchangeable.' - name: region in: query required: false schema: type: string example: US description: ISO-3166 region code (maps to regionCode) - name: max_results in: query required: false schema: type: string example: '25' description: Results per page, max 50 - name: cursor in: query required: false schema: type: string example: CAUQAA description: Opaque page token from a previous response - name: include_metrics in: query required: false schema: type: string enum: - 'true' - 'false' x-value-aliases: '0': 'false' '1': 'true' example: 'true' description: 'Opt in to one bounded video-metrics batch and one channel-handle batch at the same one-credit price. Original records, precise dates and continuation survive partial enrichment. Check data.enrichment for completion. Accepted values: true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: dry_run in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: judgments in: query required: false schema: type: string enum: - 'on' - 'off' example: 'on' description: 'Add bounded AI labels to eligible returned records (default on). off preserves the original data shape. Unclassified records remain present; labels depend on evidence, time, capacity and the existing request budget. No label surcharge. Accepted values: on, off. Case, spaces, hyphens and underscores are interchangeable.' - name: label in: query required: false schema: type: string enum: - default - none example: none description: 'Set none to disable labels; default enables the endpoint’s label set. Equivalent to judgments=off. Accepted values: default, none. Case, spaces, hyphens and underscores are interchangeable.' - name: label_evidence in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Include exact supporting sentences and zero-based sentence indexes when a label has validated evidence. No extra charge or change to decisions. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: exclude in: query required: false schema: type: string enum: - engagement_bait example: engagement_bait description: 'Optionally remove confidently labelled engagement bait. Uncertain and unclassified records stay; removed IDs and an owner-bound recall reference are returned. Accepted values: engagement_bait. Case, spaces, hyphens and underscores are interchangeable.' - name: fit in: query required: false schema: type: string enum: - goal example: goal description: 'Use goal to replace confidently irrelevant records with recall stubs. Keeps first, last, relevant and uncertain records; preserves order. Full evidence is stored for 24 hours when available. Accepted values: goal. Case, spaces, hyphens and underscores are interchangeable.' - name: goal in: query required: false schema: type: string example: Find concrete product complaints description: 'Required with fit=goal: describe the task in at most 600 characters. Supplied text is task context, never permission to act on posts.' - name: tokens in: query required: false schema: type: string example: '4000' description: Optional soft response target for fit=goal, 256–32000. Safety and evidence retention take priority, so the returned result may exceed it. - name: X-Max-Credits in: header required: false schema: type: integer minimum: 0 maximum: 9007199254740991 example: 5 description: Optional credit reservation ceiling for this individual request. Send a non-negative integer in decimal digits. Live execution checks the required reservation after resolving free cache hits or buffered continuation, before charging or calling a supplier. A higher reservation returns HTTP 422 INVALID_PARAMETERS with reason max_credits_exceeded and charges nothing. Invalid header values also return 422. Zero permits only a zero-credit reservation; omitting the header uses normal pricing. dry_run remains a free preview. This does not cap later requests, batches or scheduled runs. security: - ApiKeyHeader: [] - BearerKey: [] responses: '200': description: 'The common success envelope; `data` is endpoint-specific. Many lists use items/count/cursor; bundles use named collections and their documented continuation metadata. HTTP 200 can contain a partial bundle: inspect complete, partial and legs where supplied.' content: application/json: schema: allOf: - $ref: '#/components/schemas/Success' - type: object properties: data: $schema: https://json-schema.org/draft/2020-12/schema $id: https://www.monocrawl.com/schemas/youtube/search.json title: youtube/search data fields description: Required core structure for successful data, with optional source fields. Additional fields are allowed. This is not a completeness guarantee. type: object properties: items: type: array items: type: object properties: kind: type: - string - 'null' description: 'Result kind: video, channel or playlist.' id: type: - string - 'null' description: Source identifier. Preserve its exact string value; do not convert large IDs to numbers. url: type: - string - 'null' description: Original source URL when supplied. title: type: - string - 'null' description: Search-result title. description: type: - string - 'null' description: Search snippet, not the full video description. published_at: type: - string - 'null' description: Source publication time, normalized to an ISO date-time when available. channel: type: object properties: id: type: - string - 'null' description: Source identifier. Preserve its exact string value; do not convert large IDs to numbers. name: type: - string - 'null' description: Channel display name. handle: type: - string - 'null' description: Optional public channel handle from include_metrics=true. avatar_url: type: - string - 'null' description: Original source URL when supplied. subscribers: type: - number - 'null' description: Public subscribers; can be rounded reported by the source; null or absent is unknown, not zero. subscribers_hidden: type: - boolean - 'null' description: Whether public subscribers are hidden. additionalProperties: true metrics: type: - object - 'null' properties: views: type: - number - 'null' description: Views reported by the source; null or absent is unknown, not zero. likes: type: - number - 'null' description: Likes reported by the source; null or absent is unknown, not zero. comments: type: - number - 'null' description: Comments reported by the source; null or absent is unknown, not zero. duration_seconds: type: - number - 'null' description: Duration in seconds. additionalProperties: true description: Optional include_metrics=true enrichment; null if the video detail is unavailable. additionalProperties: true allOf: - anyOf: - required: - id properties: id: type: - string description: Source identifier. Preserve its exact string value; do not convert large IDs to numbers. minLength: 1 - required: - url properties: url: type: - string description: Original source URL when supplied. minLength: 1 - required: - title properties: title: type: - string description: Search-result title. minLength: 1 - required: - description properties: description: type: - string description: Search snippet, not the full video description. minLength: 1 - required: - published_at properties: published_at: type: - string description: Source publication time, normalized to an ISO date-time when available. minLength: 1 - required: - channel properties: channel: type: object properties: id: type: - string - 'null' description: Source identifier. Preserve its exact string value; do not convert large IDs to numbers. name: type: - string - 'null' description: Channel display name. handle: type: - string - 'null' description: Optional public channel handle from include_metrics=true. avatar_url: type: - string - 'null' description: Original source URL when supplied. subscribers: type: - number - 'null' description: Public subscribers; can be rounded reported by the source; null or absent is unknown, not zero. subscribers_hidden: type: - boolean - 'null' description: Whether public subscribers are hidden. additionalProperties: true - required: - metrics properties: metrics: type: - object properties: views: type: - number - 'null' description: Views reported by the source; null or absent is unknown, not zero. likes: type: - number - 'null' description: Likes reported by the source; null or absent is unknown, not zero. comments: type: - number - 'null' description: Comments reported by the source; null or absent is unknown, not zero. duration_seconds: type: - number - 'null' description: Duration in seconds. additionalProperties: true description: Optional include_metrics=true enrichment; null if the video detail is unavailable. description: Records in this response page. count: type: - number - 'null' description: Returned row count when supplied; not the full source total. cursor: type: - string - 'null' description: Opaque next-page token. A missing token does not prove full history was retrieved. has_more: type: - boolean - 'null' description: Source continuation indicator; null means unknown. enrichment: type: object properties: metrics: type: - string - 'null' description: ok, partial, unavailable or not_needed. ok requires views and duration for every distinct video; engagement counts may still be null. channels: type: - string - 'null' description: ok, partial, unavailable or not_needed. videos_matched: type: - number - 'null' description: Distinct video IDs matched in the optional batch. channels_matched: type: - number - 'null' description: Distinct channel IDs with at least one optional field. channel_handles_matched: type: - number - 'null' description: Distinct channel IDs with handles. channel_avatars_matched: type: - number - 'null' description: Distinct channel IDs with avatars. channel_subscribers_matched: type: - number - 'null' description: Distinct channel IDs with public subscriber counts. additionalProperties: true _warnings: type: array items: type: string description: Collection limitations or component warnings. Read before interpreting coverage. additionalProperties: true required: - items x-contract-version: '2026-09-22' x-validation-scope: Required success payload structure; optional fields and source completeness remain separate. examples: - items: - kind: video id: abcdefghijk url: https://www.youtube.com/watch?v=abcdefghijk title: A quieter desk setup channel: id: UC_example name: Example Channel cursor: null has_more: null default: description: The error envelope — the same shape for every non-2xx status. content: application/json: schema: $ref: '#/components/schemas/Error' x-credits: 1 x-production-available: true x-capacity: status: not_assessed message: Capacity is workload-dependent; configured routes do not establish sustained throughput or an availability guarantee. x-availability-scope: Structural check of the effective registered chain, production permission, adapter, configured cost and quality floor without request parameters. True is not a live-health, credential, quota, subscription-entitlement, complete-data or deployment-exposure guarantee. False means no structurally eligible candidate; null means metadata could not establish availability. Composite child capability still depends on its component routes. x-live-proven: true /v1/youtube/search/advanced: get: operationId: youtube_search_advanced tags: - Youtube summary: YouTube advanced search description: Advanced YouTube search exposing the Data API search.list filters (order, duration, event/type, category, geo, dates, captions and more). Costs 1 credit per successful live response. parameters: - name: query in: query required: true schema: type: string example: machine learning description: Search query - name: order in: query required: false schema: type: string enum: - relevance - date - rating - title - viewCount example: viewCount description: 'relevance, date, rating, title or viewCount Accepted values: relevance, date, rating, title, viewCount. Case, spaces, hyphens and underscores are interchangeable.' - name: duration in: query required: false schema: type: string enum: - short - medium - long example: long description: 'short, medium or long (forces video results) Accepted values: short, medium, long. Case, spaces, hyphens and underscores are interchangeable.' - name: event_type in: query required: false schema: type: string enum: - live - upcoming - completed example: completed description: 'live, upcoming or completed (forces video results) Accepted values: live, upcoming, completed. Case, spaces, hyphens and underscores are interchangeable.' - name: license in: query required: false schema: type: string enum: - any - creativeCommon - youtube example: creativeCommon description: 'any, creativeCommon or youtube (maps to videoLicense) Accepted values: any, creativeCommon, youtube. Case, spaces, hyphens and underscores are interchangeable.' - name: category in: query required: false schema: type: string example: '28' description: videoCategoryId - name: region in: query required: false schema: type: string example: US description: ISO-3166 region code (maps to regionCode) - name: language in: query required: false schema: type: string example: en description: Preferred content language (maps to relevanceLanguage) - name: published_after in: query required: false schema: type: string example: '2024-01-01T00:00:00Z' description: RFC-3339 lower bound (maps to publishedAfter) - name: published_before in: query required: false schema: type: string example: '2025-01-01T00:00:00Z' description: RFC-3339 upper bound (maps to publishedBefore) - name: channel_id in: query required: false schema: type: string example: UC_x5XG1OV2P6uZZ5FSM9Ttw description: Restrict to a channel (maps to channelId) - name: safe_search in: query required: false schema: type: string enum: - none - moderate - strict example: moderate description: 'none, moderate or strict (maps to safeSearch) Accepted values: none, moderate, strict. Case, spaces, hyphens and underscores are interchangeable.' - name: video_caption in: query required: false schema: type: string enum: - any - closedCaption - none example: closedCaption description: 'any, closedCaption or none (maps to videoCaption) Accepted values: any, closedCaption, none. Case, spaces, hyphens and underscores are interchangeable.' - name: video_definition in: query required: false schema: type: string enum: - any - standard - high example: high description: 'any, standard or high (maps to videoDefinition) Accepted values: any, standard, high. Case, spaces, hyphens and underscores are interchangeable.' - name: video_dimension in: query required: false schema: type: string enum: - 2d - 3d - any example: 2d description: '2d, 3d or any (maps to videoDimension) Accepted values: 2d, 3d, any. Case, spaces, hyphens and underscores are interchangeable.' - name: video_embeddable in: query required: false schema: type: string enum: - 'true' - any example: 'true' description: 'true or any (maps to videoEmbeddable) Accepted values: true, any. Case, spaces, hyphens and underscores are interchangeable.' - name: video_type in: query required: false schema: type: string enum: - any - episode - movie example: movie description: 'any, episode or movie (maps to videoType) Accepted values: any, episode, movie. Case, spaces, hyphens and underscores are interchangeable.' - name: topic_id in: query required: false schema: type: string example: /m/019_rr description: Freebase topic id (maps to topicId) - name: location in: query required: false schema: type: string example: 37.42307,-122.08427 description: lat,long point (maps to location; requires location_radius) - name: location_radius in: query required: false schema: type: string example: 10km description: Search radius, e.g. 10km (maps to locationRadius) - name: max_results in: query required: false schema: type: string example: '50' description: Requested page size, 1–50. The paid primary defaults to 50; the source may return fewer. Keep an explicit size unchanged while paginating. - name: cursor in: query required: false schema: type: string example: CAUQAA description: Opaque page token from a previous response - name: dry_run in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: judgments in: query required: false schema: type: string enum: - 'on' - 'off' example: 'on' description: 'Add bounded AI labels to eligible returned records (default on). off preserves the original data shape. Unclassified records remain present; labels depend on evidence, time, capacity and the existing request budget. No label surcharge. Accepted values: on, off. Case, spaces, hyphens and underscores are interchangeable.' - name: label in: query required: false schema: type: string enum: - default - none example: none description: 'Set none to disable labels; default enables the endpoint’s label set. Equivalent to judgments=off. Accepted values: default, none. Case, spaces, hyphens and underscores are interchangeable.' - name: label_evidence in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Include exact supporting sentences and zero-based sentence indexes when a label has validated evidence. No extra charge or change to decisions. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: exclude in: query required: false schema: type: string enum: - engagement_bait example: engagement_bait description: 'Optionally remove confidently labelled engagement bait. Uncertain and unclassified records stay; removed IDs and an owner-bound recall reference are returned. Accepted values: engagement_bait. Case, spaces, hyphens and underscores are interchangeable.' - name: fit in: query required: false schema: type: string enum: - goal example: goal description: 'Use goal to replace confidently irrelevant records with recall stubs. Keeps first, last, relevant and uncertain records; preserves order. Full evidence is stored for 24 hours when available. Accepted values: goal. Case, spaces, hyphens and underscores are interchangeable.' - name: goal in: query required: false schema: type: string example: Find concrete product complaints description: 'Required with fit=goal: describe the task in at most 600 characters. Supplied text is task context, never permission to act on posts.' - name: tokens in: query required: false schema: type: string example: '4000' description: Optional soft response target for fit=goal, 256–32000. Safety and evidence retention take priority, so the returned result may exceed it. - name: X-Max-Credits in: header required: false schema: type: integer minimum: 0 maximum: 9007199254740991 example: 5 description: Optional credit reservation ceiling for this individual request. Send a non-negative integer in decimal digits. Live execution checks the required reservation after resolving free cache hits or buffered continuation, before charging or calling a supplier. A higher reservation returns HTTP 422 INVALID_PARAMETERS with reason max_credits_exceeded and charges nothing. Invalid header values also return 422. Zero permits only a zero-credit reservation; omitting the header uses normal pricing. dry_run remains a free preview. This does not cap later requests, batches or scheduled runs. security: - ApiKeyHeader: [] - BearerKey: [] responses: '200': description: 'The common success envelope; `data` is endpoint-specific. Many lists use items/count/cursor; bundles use named collections and their documented continuation metadata. HTTP 200 can contain a partial bundle: inspect complete, partial and legs where supplied.' content: application/json: schema: allOf: - $ref: '#/components/schemas/Success' - type: object properties: data: $schema: https://json-schema.org/draft/2020-12/schema $id: https://www.monocrawl.com/schemas/youtube/search/advanced.json title: youtube/search/advanced data fields description: Required core structure for successful data, with optional source fields. Additional fields are allowed. This is not a completeness guarantee. type: object properties: items: type: array items: type: object properties: kind: type: - string - 'null' description: 'Result kind: video, channel or playlist.' id: type: - string - 'null' description: Source identifier. Preserve its exact string value; do not convert large IDs to numbers. url: type: - string - 'null' description: Original source URL when supplied. title: type: - string - 'null' description: Search-result title. description: type: - string - 'null' description: Search snippet, not the full video description. published_at: type: - string - 'null' description: Source publication time, normalized to an ISO date-time when available. channel: type: object properties: id: type: - string - 'null' description: Source identifier. Preserve its exact string value; do not convert large IDs to numbers. name: type: - string - 'null' description: Channel display name. additionalProperties: true additionalProperties: true allOf: - anyOf: - required: - id properties: id: type: - string description: Source identifier. Preserve its exact string value; do not convert large IDs to numbers. minLength: 1 - required: - url properties: url: type: - string description: Original source URL when supplied. minLength: 1 - required: - title properties: title: type: - string description: Search-result title. minLength: 1 - required: - description properties: description: type: - string description: Search snippet, not the full video description. minLength: 1 - required: - published_at properties: published_at: type: - string description: Source publication time, normalized to an ISO date-time when available. minLength: 1 - required: - channel properties: channel: type: object properties: id: type: - string - 'null' description: Source identifier. Preserve its exact string value; do not convert large IDs to numbers. name: type: - string - 'null' description: Channel display name. additionalProperties: true description: Records in this response page. count: type: - number - 'null' description: Returned row count when supplied; not the full source total. cursor: type: - string - 'null' description: Opaque next-page token. A missing token does not prove full history was retrieved. has_more: type: - boolean - 'null' description: Source continuation indicator; null means unknown. _warnings: type: array items: type: string description: Collection limitations or component warnings. Read before interpreting coverage. additionalProperties: true required: - items x-contract-version: '2026-09-22' x-validation-scope: Required success payload structure; optional fields and source completeness remain separate. examples: - items: - kind: video id: abcdefghijk url: https://www.youtube.com/watch?v=abcdefghijk title: A quieter desk setup channel: id: UC_example name: Example Channel cursor: null has_more: null default: description: The error envelope — the same shape for every non-2xx status. content: application/json: schema: $ref: '#/components/schemas/Error' x-credits: 1 x-production-available: true x-capacity: status: not_assessed message: Capacity is workload-dependent; configured routes do not establish sustained throughput or an availability guarantee. x-availability-scope: Structural check of the effective registered chain, production permission, adapter, configured cost and quality floor without request parameters. True is not a live-health, credential, quota, subscription-entitlement, complete-data or deployment-exposure guarantee. False means no structurally eligible candidate; null means metadata could not establish availability. Composite child capability still depends on its component routes. x-live-proven: true /v1/youtube/search/hashtag: get: operationId: youtube_search_hashtag tags: - Youtube summary: YouTube hashtag search description: Best-effort hashtag search — a search.list keyword query for the "#tag" token (Data API has no dedicated hashtag endpoint; noted in _warnings). Costs 1 credit per successful live response. parameters: - name: hashtag in: query required: true schema: type: string example: shorts description: 'Hashtag with or without the leading #' - name: type in: query required: false schema: type: array items: type: string enum: - video - channel - playlist style: form explode: false example: - video description: 'Result kind (defaults to video) Accepted values (comma-separated): video, channel, playlist. Case, spaces, hyphens and underscores are interchangeable.' - name: max_results in: query required: false schema: type: string example: '50' description: Requested page size, 1–50. The paid primary defaults to 50; the source may return fewer. Keep an explicit size unchanged while paginating. - name: cursor in: query required: false schema: type: string example: CAUQAA description: Opaque page token from a previous response - name: dry_run in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: judgments in: query required: false schema: type: string enum: - 'on' - 'off' example: 'on' description: 'Add bounded AI labels to eligible returned records (default on). off preserves the original data shape. Unclassified records remain present; labels depend on evidence, time, capacity and the existing request budget. No label surcharge. Accepted values: on, off. Case, spaces, hyphens and underscores are interchangeable.' - name: label in: query required: false schema: type: string enum: - default - none example: none description: 'Set none to disable labels; default enables the endpoint’s label set. Equivalent to judgments=off. Accepted values: default, none. Case, spaces, hyphens and underscores are interchangeable.' - name: label_evidence in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Include exact supporting sentences and zero-based sentence indexes when a label has validated evidence. No extra charge or change to decisions. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: exclude in: query required: false schema: type: string enum: - engagement_bait example: engagement_bait description: 'Optionally remove confidently labelled engagement bait. Uncertain and unclassified records stay; removed IDs and an owner-bound recall reference are returned. Accepted values: engagement_bait. Case, spaces, hyphens and underscores are interchangeable.' - name: fit in: query required: false schema: type: string enum: - goal example: goal description: 'Use goal to replace confidently irrelevant records with recall stubs. Keeps first, last, relevant and uncertain records; preserves order. Full evidence is stored for 24 hours when available. Accepted values: goal. Case, spaces, hyphens and underscores are interchangeable.' - name: goal in: query required: false schema: type: string example: Find concrete product complaints description: 'Required with fit=goal: describe the task in at most 600 characters. Supplied text is task context, never permission to act on posts.' - name: tokens in: query required: false schema: type: string example: '4000' description: Optional soft response target for fit=goal, 256–32000. Safety and evidence retention take priority, so the returned result may exceed it. - name: X-Max-Credits in: header required: false schema: type: integer minimum: 0 maximum: 9007199254740991 example: 5 description: Optional credit reservation ceiling for this individual request. Send a non-negative integer in decimal digits. Live execution checks the required reservation after resolving free cache hits or buffered continuation, before charging or calling a supplier. A higher reservation returns HTTP 422 INVALID_PARAMETERS with reason max_credits_exceeded and charges nothing. Invalid header values also return 422. Zero permits only a zero-credit reservation; omitting the header uses normal pricing. dry_run remains a free preview. This does not cap later requests, batches or scheduled runs. security: - ApiKeyHeader: [] - BearerKey: [] responses: '200': description: 'The common success envelope; `data` is endpoint-specific. Many lists use items/count/cursor; bundles use named collections and their documented continuation metadata. HTTP 200 can contain a partial bundle: inspect complete, partial and legs where supplied.' content: application/json: schema: allOf: - $ref: '#/components/schemas/Success' - type: object properties: data: $schema: https://json-schema.org/draft/2020-12/schema $id: https://www.monocrawl.com/schemas/youtube/search/hashtag.json title: youtube/search/hashtag data fields description: Required core structure for successful data, with optional source fields. Additional fields are allowed. This is not a completeness guarantee. type: object properties: items: type: array items: type: object properties: kind: type: - string - 'null' description: 'Result kind: video, channel or playlist.' id: type: - string - 'null' description: Source identifier. Preserve its exact string value; do not convert large IDs to numbers. url: type: - string - 'null' description: Original source URL when supplied. title: type: - string - 'null' description: Search-result title. description: type: - string - 'null' description: Search snippet, not the full video description. published_at: type: - string - 'null' description: Source publication time, normalized to an ISO date-time when available. channel: type: object properties: id: type: - string - 'null' description: Source identifier. Preserve its exact string value; do not convert large IDs to numbers. name: type: - string - 'null' description: Channel display name. additionalProperties: true additionalProperties: true allOf: - anyOf: - required: - id properties: id: type: - string description: Source identifier. Preserve its exact string value; do not convert large IDs to numbers. minLength: 1 - required: - url properties: url: type: - string description: Original source URL when supplied. minLength: 1 - required: - title properties: title: type: - string description: Search-result title. minLength: 1 - required: - description properties: description: type: - string description: Search snippet, not the full video description. minLength: 1 - required: - published_at properties: published_at: type: - string description: Source publication time, normalized to an ISO date-time when available. minLength: 1 - required: - channel properties: channel: type: object properties: id: type: - string - 'null' description: Source identifier. Preserve its exact string value; do not convert large IDs to numbers. name: type: - string - 'null' description: Channel display name. additionalProperties: true description: Records in this response page. count: type: - number - 'null' description: Returned row count when supplied; not the full source total. cursor: type: - string - 'null' description: Opaque next-page token. A missing token does not prove full history was retrieved. has_more: type: - boolean - 'null' description: Source continuation indicator; null means unknown. _warnings: type: array items: type: string description: Collection limitations or component warnings. Read before interpreting coverage. additionalProperties: true required: - items x-contract-version: '2026-09-22' x-validation-scope: Required success payload structure; optional fields and source completeness remain separate. examples: - items: - kind: video id: abcdefghijk url: https://www.youtube.com/watch?v=abcdefghijk title: A quieter desk setup channel: id: UC_example name: Example Channel cursor: null has_more: null default: description: The error envelope — the same shape for every non-2xx status. content: application/json: schema: $ref: '#/components/schemas/Error' x-credits: 1 x-production-available: true x-capacity: status: not_assessed message: Capacity is workload-dependent; configured routes do not establish sustained throughput or an availability guarantee. x-availability-scope: Structural check of the effective registered chain, production permission, adapter, configured cost and quality floor without request parameters. True is not a live-health, credential, quota, subscription-entitlement, complete-data or deployment-exposure guarantee. False means no structurally eligible candidate; null means metadata could not establish availability. Composite child capability still depends on its component routes. x-live-proven: true /v1/youtube/shorts: get: operationId: youtube_shorts tags: - Youtube summary: Channel Shorts description: 'A channel''s Shorts shelf: title, URL, views, likes and comments per short. Paged by cursor. Costs 1 credit per successful live response.' parameters: - name: handle in: query required: true schema: type: string example: starterstory description: Channel handle without the @ (or pass channelId). - name: channelId in: query required: false schema: type: string description: Channel id — alternative to handle. - name: sort in: query required: false schema: type: string enum: - newest - popular description: 'newest or popular. Accepted values: newest, popular. Case, spaces, hyphens and underscores are interchangeable.' - name: cursor in: query required: false schema: type: string description: continuationToken from the previous page. - name: dry_run in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: judgments in: query required: false schema: type: string enum: - 'on' - 'off' example: 'on' description: 'Add bounded AI labels to eligible returned records (default on). off preserves the original data shape. Unclassified records remain present; labels depend on evidence, time, capacity and the existing request budget. No label surcharge. Accepted values: on, off. Case, spaces, hyphens and underscores are interchangeable.' - name: label in: query required: false schema: type: string enum: - default - none example: none description: 'Set none to disable labels; default enables the endpoint’s label set. Equivalent to judgments=off. Accepted values: default, none. Case, spaces, hyphens and underscores are interchangeable.' - name: label_evidence in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Include exact supporting sentences and zero-based sentence indexes when a label has validated evidence. No extra charge or change to decisions. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: exclude in: query required: false schema: type: string enum: - engagement_bait example: engagement_bait description: 'Optionally remove confidently labelled engagement bait. Uncertain and unclassified records stay; removed IDs and an owner-bound recall reference are returned. Accepted values: engagement_bait. Case, spaces, hyphens and underscores are interchangeable.' - name: fit in: query required: false schema: type: string enum: - goal example: goal description: 'Use goal to replace confidently irrelevant records with recall stubs. Keeps first, last, relevant and uncertain records; preserves order. Full evidence is stored for 24 hours when available. Accepted values: goal. Case, spaces, hyphens and underscores are interchangeable.' - name: goal in: query required: false schema: type: string example: Find concrete product complaints description: 'Required with fit=goal: describe the task in at most 600 characters. Supplied text is task context, never permission to act on posts.' - name: tokens in: query required: false schema: type: string example: '4000' description: Optional soft response target for fit=goal, 256–32000. Safety and evidence retention take priority, so the returned result may exceed it. - name: X-Max-Credits in: header required: false schema: type: integer minimum: 0 maximum: 9007199254740991 example: 5 description: Optional credit reservation ceiling for this individual request. Send a non-negative integer in decimal digits. Live execution checks the required reservation after resolving free cache hits or buffered continuation, before charging or calling a supplier. A higher reservation returns HTTP 422 INVALID_PARAMETERS with reason max_credits_exceeded and charges nothing. Invalid header values also return 422. Zero permits only a zero-credit reservation; omitting the header uses normal pricing. dry_run remains a free preview. This does not cap later requests, batches or scheduled runs. security: - ApiKeyHeader: [] - BearerKey: [] responses: '200': description: 'The common success envelope; `data` is endpoint-specific. Many lists use items/count/cursor; bundles use named collections and their documented continuation metadata. HTTP 200 can contain a partial bundle: inspect complete, partial and legs where supplied.' content: application/json: schema: allOf: - $ref: '#/components/schemas/Success' - type: object properties: data: $schema: https://json-schema.org/draft/2020-12/schema $id: https://www.monocrawl.com/schemas/youtube/shorts.json title: youtube/shorts data fields description: Optional data supplied by this operation. Null means unknown. type: object properties: cursor: description: Opaque next-page token; pass it back unchanged. Null does not prove complete history. type: - string - 'null' dropped: description: Optional dropped supplied by this operation. Null means unknown. type: - number - 'null' items: description: Returned records. Source coverage and completeness vary. type: - array items: description: Optional record supplied by this operation. Null means unknown. type: object properties: caption_tracks: description: Source array was empty in the reviewed captures; item fields remain unspecified. type: - array - 'null' items: {} channel: description: Optional channel supplied by this operation. Null means unknown. type: - object - 'null' properties: {} additionalProperties: true comments_count: description: Optional comments count supplied by this operation. Null means unknown. type: - number - 'null' description: description: Source description; null or absent means not supplied. type: - string - 'null' duration_ms: description: Optional duration ms supplied by this operation. Null means unknown. type: - number - 'null' genre: description: Optional genre supplied by this operation. Null means unknown. type: - string - 'null' id: description: Source identifier. Preserve the supplied type and exact value. type: - string - 'null' keywords: description: Source array was empty in the reviewed captures; item fields remain unspecified. type: - array - 'null' items: {} likes: description: Optional likes supplied by this operation. Null means unknown. type: - number - 'null' platform: description: Optional platform supplied by this operation. Null means unknown. type: - string - 'null' published: description: Optional published supplied by this operation. Null means unknown. type: - string - 'null' published_at: description: Source publication time when available. type: - string - 'null' thumbnail: description: Optional thumbnail supplied by this operation. Null means unknown. type: - string - 'null' title: description: Source title when supplied. type: - string - 'null' url: description: Original source URL when supplied. type: - string - 'null' views: description: Optional views supplied by this operation. Null means unknown. type: - number - 'null' additionalProperties: true allOf: - anyOf: - required: - caption_tracks properties: caption_tracks: description: Source array was empty in the reviewed captures; item fields remain unspecified. type: - array items: {} - required: - channel properties: channel: description: Optional channel supplied by this operation. Null means unknown. type: - object properties: {} additionalProperties: true - required: - comments_count properties: comments_count: description: Optional comments count supplied by this operation. Null means unknown. type: - number - required: - description properties: description: description: Source description; null or absent means not supplied. type: - string minLength: 1 - required: - duration_ms properties: duration_ms: description: Optional duration ms supplied by this operation. Null means unknown. type: - number - required: - genre properties: genre: description: Optional genre supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - id properties: id: description: Source identifier. Preserve the supplied type and exact value. type: - string minLength: 1 - required: - keywords properties: keywords: description: Source array was empty in the reviewed captures; item fields remain unspecified. type: - array items: {} - required: - likes properties: likes: description: Optional likes supplied by this operation. Null means unknown. type: - number - required: - published properties: published: description: Optional published supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - published_at properties: published_at: description: Source publication time when available. type: - string minLength: 1 - required: - thumbnail properties: thumbnail: description: Optional thumbnail supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - title properties: title: description: Source title when supplied. type: - string minLength: 1 - required: - url properties: url: description: Original source URL when supplied. type: - string minLength: 1 - required: - views properties: views: description: Optional views supplied by this operation. Null means unknown. type: - number additionalProperties: true required: - items x-contract-version: '2026-09-22' x-validation-scope: Required success payload structure; optional fields and source completeness remain separate. examples: - cursor: null dropped: 0 items: - caption_tracks: [] channel: {} comments_count: 0 description: example duration_ms: 0 genre: example id: example keywords: [] likes: 0 platform: example published: example published_at: '2026-09-01T12:00:00Z' thumbnail: example title: example url: https://example.com/example views: 0 default: description: The error envelope — the same shape for every non-2xx status. content: application/json: schema: $ref: '#/components/schemas/Error' x-credits: 1 x-production-available: true x-capacity: status: not_assessed message: Capacity is workload-dependent; configured routes do not establish sustained throughput or an availability guarantee. x-availability-scope: Structural check of the effective registered chain, production permission, adapter, configured cost and quality floor without request parameters. True is not a live-health, credential, quota, subscription-entitlement, complete-data or deployment-exposure guarantee. False means no structurally eligible candidate; null means metadata could not establish availability. Composite child capability still depends on its component routes. x-live-proven: true /v1/youtube/shorts-trending: get: operationId: youtube_shorts_trending tags: - Youtube summary: Trending Shorts description: The current trending Shorts feed with engagement counts. Costs 4 credits per successful live response. parameters: - name: dry_run in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: judgments in: query required: false schema: type: string enum: - 'on' - 'off' example: 'on' description: 'Add bounded AI labels to eligible returned records (default on). off preserves the original data shape. Unclassified records remain present; labels depend on evidence, time, capacity and the existing request budget. No label surcharge. Accepted values: on, off. Case, spaces, hyphens and underscores are interchangeable.' - name: label in: query required: false schema: type: string enum: - default - none example: none description: 'Set none to disable labels; default enables the endpoint’s label set. Equivalent to judgments=off. Accepted values: default, none. Case, spaces, hyphens and underscores are interchangeable.' - name: label_evidence in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Include exact supporting sentences and zero-based sentence indexes when a label has validated evidence. No extra charge or change to decisions. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: exclude in: query required: false schema: type: string enum: - engagement_bait example: engagement_bait description: 'Optionally remove confidently labelled engagement bait. Uncertain and unclassified records stay; removed IDs and an owner-bound recall reference are returned. Accepted values: engagement_bait. Case, spaces, hyphens and underscores are interchangeable.' - name: fit in: query required: false schema: type: string enum: - goal example: goal description: 'Use goal to replace confidently irrelevant records with recall stubs. Keeps first, last, relevant and uncertain records; preserves order. Full evidence is stored for 24 hours when available. Accepted values: goal. Case, spaces, hyphens and underscores are interchangeable.' - name: goal in: query required: false schema: type: string example: Find concrete product complaints description: 'Required with fit=goal: describe the task in at most 600 characters. Supplied text is task context, never permission to act on posts.' - name: tokens in: query required: false schema: type: string example: '4000' description: Optional soft response target for fit=goal, 256–32000. Safety and evidence retention take priority, so the returned result may exceed it. - name: X-Max-Credits in: header required: false schema: type: integer minimum: 0 maximum: 9007199254740991 example: 5 description: Optional credit reservation ceiling for this individual request. Send a non-negative integer in decimal digits. Live execution checks the required reservation after resolving free cache hits or buffered continuation, before charging or calling a supplier. A higher reservation returns HTTP 422 INVALID_PARAMETERS with reason max_credits_exceeded and charges nothing. Invalid header values also return 422. Zero permits only a zero-credit reservation; omitting the header uses normal pricing. dry_run remains a free preview. This does not cap later requests, batches or scheduled runs. security: - ApiKeyHeader: [] - BearerKey: [] responses: '200': description: 'The common success envelope; `data` is endpoint-specific. Many lists use items/count/cursor; bundles use named collections and their documented continuation metadata. HTTP 200 can contain a partial bundle: inspect complete, partial and legs where supplied.' content: application/json: schema: allOf: - $ref: '#/components/schemas/Success' - type: object properties: data: $schema: https://json-schema.org/draft/2020-12/schema $id: https://www.monocrawl.com/schemas/youtube/shorts-trending.json title: youtube/shorts-trending data fields description: Optional data supplied by this operation. Null means unknown. type: object properties: items: description: Returned records. Source coverage and completeness vary. type: - array items: description: Optional record supplied by this operation. Null means unknown. type: object properties: caption_tracks: description: Source array was empty in the reviewed captures; item fields remain unspecified. type: - array - 'null' items: {} channel: description: Optional channel supplied by this operation. Null means unknown. type: - object - 'null' properties: handle: description: Optional handle supplied by this operation. Null means unknown. type: - string - 'null' id: description: Source identifier. Preserve the supplied type and exact value. type: - string - 'null' title: description: Source title when supplied. type: - string - 'null' url: description: Original source URL when supplied. type: - string - 'null' additionalProperties: true comments_count: description: Optional comments count supplied by this operation. Null means unknown. type: - number - 'null' description: description: Source description; null or absent means not supplied. type: - string - 'null' duration_ms: description: Optional duration ms supplied by this operation. Null means unknown. type: - number - 'null' genre: description: Optional genre supplied by this operation. Null means unknown. type: - string - 'null' id: description: Source identifier. Preserve the supplied type and exact value. type: - string - 'null' keywords: description: Optional keywords supplied by this operation. Null means unknown. type: - array - 'null' items: description: Optional record supplied by this operation. Null means unknown. type: - string - 'null' likes: description: Optional likes supplied by this operation. Null means unknown. type: - number - 'null' platform: description: Optional platform supplied by this operation. Null means unknown. type: - string - 'null' published: description: Optional published supplied by this operation. Null means unknown. type: - string - 'null' published_at: description: Source publication time when available. type: - string - 'null' thumbnail: description: Optional thumbnail supplied by this operation. Null means unknown. type: - string - 'null' title: description: Source title when supplied. type: - string - 'null' url: description: Original source URL when supplied. type: - string - 'null' views: description: Optional views supplied by this operation. Null means unknown. type: - number - 'null' additionalProperties: true allOf: - anyOf: - required: - caption_tracks properties: caption_tracks: description: Source array was empty in the reviewed captures; item fields remain unspecified. type: - array items: {} - required: - channel properties: channel: description: Optional channel supplied by this operation. Null means unknown. type: - object properties: handle: description: Optional handle supplied by this operation. Null means unknown. type: - string - 'null' id: description: Source identifier. Preserve the supplied type and exact value. type: - string - 'null' title: description: Source title when supplied. type: - string - 'null' url: description: Original source URL when supplied. type: - string - 'null' additionalProperties: true - required: - comments_count properties: comments_count: description: Optional comments count supplied by this operation. Null means unknown. type: - number - required: - description properties: description: description: Source description; null or absent means not supplied. type: - string minLength: 1 - required: - duration_ms properties: duration_ms: description: Optional duration ms supplied by this operation. Null means unknown. type: - number - required: - genre properties: genre: description: Optional genre supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - id properties: id: description: Source identifier. Preserve the supplied type and exact value. type: - string minLength: 1 - required: - keywords properties: keywords: description: Optional keywords supplied by this operation. Null means unknown. type: - array items: description: Optional record supplied by this operation. Null means unknown. type: - string - 'null' - required: - likes properties: likes: description: Optional likes supplied by this operation. Null means unknown. type: - number - required: - published properties: published: description: Optional published supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - published_at properties: published_at: description: Source publication time when available. type: - string minLength: 1 - required: - thumbnail properties: thumbnail: description: Optional thumbnail supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - title properties: title: description: Source title when supplied. type: - string minLength: 1 - required: - url properties: url: description: Original source URL when supplied. type: - string minLength: 1 - required: - views properties: views: description: Optional views supplied by this operation. Null means unknown. type: - number additionalProperties: true required: - items x-contract-version: '2026-09-22' x-validation-scope: Required success payload structure; optional fields and source completeness remain separate. examples: - items: - caption_tracks: [] channel: handle: example id: example title: example url: https://example.com/example comments_count: 0 description: example duration_ms: 0 genre: example id: example keywords: - example likes: 0 platform: example published: example published_at: '2026-09-01T12:00:00Z' thumbnail: example title: example url: https://example.com/example views: 0 default: description: The error envelope — the same shape for every non-2xx status. content: application/json: schema: $ref: '#/components/schemas/Error' x-credits: 4 x-production-available: true x-capacity: status: not_assessed message: Capacity is workload-dependent; configured routes do not establish sustained throughput or an availability guarantee. x-availability-scope: Structural check of the effective registered chain, production permission, adapter, configured cost and quality floor without request parameters. True is not a live-health, credential, quota, subscription-entitlement, complete-data or deployment-exposure guarantee. False means no structurally eligible candidate; null means metadata could not establish availability. Composite child capability still depends on its component routes. x-live-proven: true /v1/youtube/typeahead: get: operationId: youtube_typeahead tags: - Youtube summary: Search suggestions description: YouTube's own search suggestions for a query — channels are identified with id and handle. Keyword-research signal. Costs 2 credits per successful live response. parameters: - name: query in: query required: true schema: type: string example: mr beast description: Partial query. - name: dry_run in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: X-Max-Credits in: header required: false schema: type: integer minimum: 0 maximum: 9007199254740991 example: 5 description: Optional credit reservation ceiling for this individual request. Send a non-negative integer in decimal digits. Live execution checks the required reservation after resolving free cache hits or buffered continuation, before charging or calling a supplier. A higher reservation returns HTTP 422 INVALID_PARAMETERS with reason max_credits_exceeded and charges nothing. Invalid header values also return 422. Zero permits only a zero-credit reservation; omitting the header uses normal pricing. dry_run remains a free preview. This does not cap later requests, batches or scheduled runs. security: - ApiKeyHeader: [] - BearerKey: [] responses: '200': description: 'The common success envelope; `data` is endpoint-specific. Many lists use items/count/cursor; bundles use named collections and their documented continuation metadata. HTTP 200 can contain a partial bundle: inspect complete, partial and legs where supplied.' content: application/json: schema: allOf: - $ref: '#/components/schemas/Success' - type: object properties: data: $schema: https://json-schema.org/draft/2020-12/schema $id: https://www.monocrawl.com/schemas/youtube/typeahead.json title: youtube/typeahead data fields description: Optional data supplied by this operation. Null means unknown. type: object properties: suggestions: description: Optional suggestions supplied by this operation. Null means unknown. type: - array - 'null' items: description: Optional record supplied by this operation. Null means unknown. type: - object - 'null' properties: text: description: Source text when supplied. type: - string - 'null' type: description: Optional type supplied by this operation. Null means unknown. type: - string - 'null' additionalProperties: true additionalProperties: true allOf: - anyOf: - required: - suggestions properties: suggestions: description: Optional suggestions supplied by this operation. Null means unknown. type: - array items: description: Optional record supplied by this operation. Null means unknown. type: - object - 'null' properties: text: description: Source text when supplied. type: - string - 'null' type: description: Optional type supplied by this operation. Null means unknown. type: - string - 'null' additionalProperties: true x-contract-version: '2026-09-22' x-validation-scope: Required success payload structure; optional fields and source completeness remain separate. examples: - suggestions: - text: example type: example default: description: The error envelope — the same shape for every non-2xx status. content: application/json: schema: $ref: '#/components/schemas/Error' x-credits: 2 x-production-available: true x-capacity: status: not_assessed message: Capacity is workload-dependent; configured routes do not establish sustained throughput or an availability guarantee. x-availability-scope: Structural check of the effective registered chain, production permission, adapter, configured cost and quality floor without request parameters. True is not a live-health, credential, quota, subscription-entitlement, complete-data or deployment-exposure guarantee. False means no structurally eligible candidate; null means metadata could not establish availability. Composite child capability still depends on its component routes. x-live-proven: true /v1/youtube/video: get: operationId: youtube_video tags: - Youtube summary: YouTube video description: 'Full video details: title, description, duration, view/like/comment counts, thumbnails and live details. Costs 1 credit per successful live response.' parameters: - name: url in: query required: true schema: type: string example: https://www.youtube.com/watch?v=9bZkp7q19f0 description: Video URL (watch, youtu.be, /shorts/…) or a bare 11-char video id - name: hl in: query required: false schema: type: string example: en description: BCP-47 language for localized snippet text - name: include_channel in: query required: false schema: type: string enum: - 'true' - 'false' x-value-aliases: '0': 'false' '1': 'true' example: 'true' description: 'Add one bounded channel metadata lookup at the same price. Original video details survive missing enrichment; check enrichment and warnings. Accepted values: true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: dry_run in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: judgments in: query required: false schema: type: string enum: - 'on' - 'off' example: 'on' description: 'Add bounded AI labels to eligible returned records (default on). off preserves the original data shape. Unclassified records remain present; labels depend on evidence, time, capacity and the existing request budget. No label surcharge. Accepted values: on, off. Case, spaces, hyphens and underscores are interchangeable.' - name: label in: query required: false schema: type: string enum: - default - none example: none description: 'Set none to disable labels; default enables the endpoint’s label set. Equivalent to judgments=off. Accepted values: default, none. Case, spaces, hyphens and underscores are interchangeable.' - name: label_evidence in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Include exact supporting sentences and zero-based sentence indexes when a label has validated evidence. No extra charge or change to decisions. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: exclude in: query required: false schema: type: string enum: - engagement_bait example: engagement_bait description: 'Optionally remove confidently labelled engagement bait. Uncertain and unclassified records stay; removed IDs and an owner-bound recall reference are returned. Accepted values: engagement_bait. Case, spaces, hyphens and underscores are interchangeable.' - name: fit in: query required: false schema: type: string enum: - goal example: goal description: 'Use goal to replace confidently irrelevant records with recall stubs. Keeps first, last, relevant and uncertain records; preserves order. Full evidence is stored for 24 hours when available. Accepted values: goal. Case, spaces, hyphens and underscores are interchangeable.' - name: goal in: query required: false schema: type: string example: Find concrete product complaints description: 'Required with fit=goal: describe the task in at most 600 characters. Supplied text is task context, never permission to act on posts.' - name: tokens in: query required: false schema: type: string example: '4000' description: Optional soft response target for fit=goal, 256–32000. Safety and evidence retention take priority, so the returned result may exceed it. - name: X-Max-Credits in: header required: false schema: type: integer minimum: 0 maximum: 9007199254740991 example: 5 description: Optional credit reservation ceiling for this individual request. Send a non-negative integer in decimal digits. Live execution checks the required reservation after resolving free cache hits or buffered continuation, before charging or calling a supplier. A higher reservation returns HTTP 422 INVALID_PARAMETERS with reason max_credits_exceeded and charges nothing. Invalid header values also return 422. Zero permits only a zero-credit reservation; omitting the header uses normal pricing. dry_run remains a free preview. This does not cap later requests, batches or scheduled runs. security: - ApiKeyHeader: [] - BearerKey: [] responses: '200': description: 'The common success envelope; `data` is endpoint-specific. Many lists use items/count/cursor; bundles use named collections and their documented continuation metadata. HTTP 200 can contain a partial bundle: inspect complete, partial and legs where supplied.' content: application/json: schema: allOf: - $ref: '#/components/schemas/Success' - type: object properties: data: $schema: https://json-schema.org/draft/2020-12/schema $id: https://www.monocrawl.com/schemas/youtube/video.json title: youtube/video data fields description: Required core structure for successful data, with optional source fields. Additional fields are allowed. This is not a completeness guarantee. type: object properties: id: type: - string - 'null' description: Source identifier. Preserve its exact string value; do not convert large IDs to numbers. url: type: - string - 'null' description: Original source URL when supplied. title: type: - string - 'null' description: Video title. description: type: - string - 'null' description: Video description. published_at: type: - string - 'null' description: Source publication time, normalized to an ISO date-time when available. duration_seconds: type: - number - 'null' description: Duration in seconds. channel: type: object properties: id: type: - string - 'null' description: Source identifier. Preserve its exact string value; do not convert large IDs to numbers. name: type: - string - 'null' description: Channel display name. url: type: - string - 'null' description: Original source URL when supplied. handle: type: - string - 'null' description: Public channel handle with include_channel=true. avatar_url: type: - string - 'null' description: Original source URL when supplied. subscribers: type: - number - 'null' description: Public subscriber count; can be rounded reported by the source; null or absent is unknown, not zero. subscribers_hidden: type: - boolean - 'null' description: Whether public subscribers are hidden. additionalProperties: true views: type: - number - 'null' description: Views reported by the source; null or absent is unknown, not zero. likes: type: - number - 'null' description: Likes reported by the source; null or absent is unknown, not zero. comments_count: type: - number - 'null' description: Comments reported by the source; null or absent is unknown, not zero. has_paid_product_placement: type: - boolean - 'null' description: Explicit source paid-product-placement disclosure; null is unavailable, not false. enrichment: type: object properties: channels: type: - string - 'null' description: ok, partial, unavailable or not_needed. channels_matched: type: - number - 'null' description: Distinct channel IDs with at least one optional field. channel_handles_matched: type: - number - 'null' description: Distinct channel IDs with handles. channel_avatars_matched: type: - number - 'null' description: Distinct channel IDs with avatars. channel_subscribers_matched: type: - number - 'null' description: Distinct channel IDs with public subscriber counts. additionalProperties: true _warnings: type: array items: type: string description: Collection limitations or component warnings. Read before interpreting coverage. additionalProperties: true allOf: - anyOf: - required: - id properties: id: type: - string description: Source identifier. Preserve its exact string value; do not convert large IDs to numbers. minLength: 1 - required: - url properties: url: type: - string description: Original source URL when supplied. minLength: 1 - required: - title properties: title: type: - string description: Video title. minLength: 1 - required: - description properties: description: type: - string description: Video description. minLength: 1 - required: - published_at properties: published_at: type: - string description: Source publication time, normalized to an ISO date-time when available. minLength: 1 - required: - duration_seconds properties: duration_seconds: type: - number description: Duration in seconds. - required: - channel properties: channel: type: object properties: id: type: - string - 'null' description: Source identifier. Preserve its exact string value; do not convert large IDs to numbers. name: type: - string - 'null' description: Channel display name. url: type: - string - 'null' description: Original source URL when supplied. handle: type: - string - 'null' description: Public channel handle with include_channel=true. avatar_url: type: - string - 'null' description: Original source URL when supplied. subscribers: type: - number - 'null' description: Public subscriber count; can be rounded reported by the source; null or absent is unknown, not zero. subscribers_hidden: type: - boolean - 'null' description: Whether public subscribers are hidden. additionalProperties: true - required: - views properties: views: type: - number description: Views reported by the source; null or absent is unknown, not zero. - required: - likes properties: likes: type: - number description: Likes reported by the source; null or absent is unknown, not zero. - required: - comments_count properties: comments_count: type: - number description: Comments reported by the source; null or absent is unknown, not zero. - required: - has_paid_product_placement properties: has_paid_product_placement: type: - boolean description: Explicit source paid-product-placement disclosure; null is unavailable, not false. - required: - enrichment properties: enrichment: type: object properties: channels: type: - string - 'null' description: ok, partial, unavailable or not_needed. channels_matched: type: - number - 'null' description: Distinct channel IDs with at least one optional field. channel_handles_matched: type: - number - 'null' description: Distinct channel IDs with handles. channel_avatars_matched: type: - number - 'null' description: Distinct channel IDs with avatars. channel_subscribers_matched: type: - number - 'null' description: Distinct channel IDs with public subscriber counts. additionalProperties: true x-contract-version: '2026-09-22' x-validation-scope: Required success payload structure; optional fields and source completeness remain separate. examples: - id: abcdefghijk title: A quieter desk setup published_at: '2026-09-01T12:00:00Z' channel: id: UC_example name: Example Channel duration_seconds: 482 views: 12600 likes: 640 comments_count: 38 default: description: The error envelope — the same shape for every non-2xx status. content: application/json: schema: $ref: '#/components/schemas/Error' x-credits: 1 x-production-available: true x-capacity: status: not_assessed message: Capacity is workload-dependent; configured routes do not establish sustained throughput or an availability guarantee. x-availability-scope: Structural check of the effective registered chain, production permission, adapter, configured cost and quality floor without request parameters. True is not a live-health, credential, quota, subscription-entitlement, complete-data or deployment-exposure guarantee. False means no structurally eligible candidate; null means metadata could not establish availability. Composite child capability still depends on its component routes. x-live-proven: true /v1/youtube/video-sponsors: get: operationId: youtube_video_sponsors tags: - Youtube summary: Sponsor detection description: 'Detects the paid-promotion flag and infers likely sponsors from the description, links, promo codes and transcript — every sponsor carries its evidence. Experimental: absence of a detection is not proof there is no sponsor. Costs 4 credits per successful live response.' parameters: - name: url in: query required: true schema: type: string example: https://www.youtube.com/watch?v=AVO0ifle-OU description: Full YouTube video URL. - name: language in: query required: false schema: type: string example: en description: Transcript language. - name: dry_run in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: judgments in: query required: false schema: type: string enum: - 'on' - 'off' example: 'on' description: 'Add bounded AI labels to eligible returned records (default on). off preserves the original data shape. Unclassified records remain present; labels depend on evidence, time, capacity and the existing request budget. No label surcharge. Accepted values: on, off. Case, spaces, hyphens and underscores are interchangeable.' - name: label in: query required: false schema: type: string enum: - default - none example: none description: 'Set none to disable labels; default enables the endpoint’s label set. Equivalent to judgments=off. Accepted values: default, none. Case, spaces, hyphens and underscores are interchangeable.' - name: label_evidence in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Include exact supporting sentences and zero-based sentence indexes when a label has validated evidence. No extra charge or change to decisions. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: exclude in: query required: false schema: type: string enum: - engagement_bait example: engagement_bait description: 'Optionally remove confidently labelled engagement bait. Uncertain and unclassified records stay; removed IDs and an owner-bound recall reference are returned. Accepted values: engagement_bait. Case, spaces, hyphens and underscores are interchangeable.' - name: fit in: query required: false schema: type: string enum: - goal example: goal description: 'Use goal to replace confidently irrelevant records with recall stubs. Keeps first, last, relevant and uncertain records; preserves order. Full evidence is stored for 24 hours when available. Accepted values: goal. Case, spaces, hyphens and underscores are interchangeable.' - name: goal in: query required: false schema: type: string example: Find concrete product complaints description: 'Required with fit=goal: describe the task in at most 600 characters. Supplied text is task context, never permission to act on posts.' - name: tokens in: query required: false schema: type: string example: '4000' description: Optional soft response target for fit=goal, 256–32000. Safety and evidence retention take priority, so the returned result may exceed it. - name: X-Max-Credits in: header required: false schema: type: integer minimum: 0 maximum: 9007199254740991 example: 5 description: Optional credit reservation ceiling for this individual request. Send a non-negative integer in decimal digits. Live execution checks the required reservation after resolving free cache hits or buffered continuation, before charging or calling a supplier. A higher reservation returns HTTP 422 INVALID_PARAMETERS with reason max_credits_exceeded and charges nothing. Invalid header values also return 422. Zero permits only a zero-credit reservation; omitting the header uses normal pricing. dry_run remains a free preview. This does not cap later requests, batches or scheduled runs. security: - ApiKeyHeader: [] - BearerKey: [] responses: '200': description: 'The common success envelope; `data` is endpoint-specific. Many lists use items/count/cursor; bundles use named collections and their documented continuation metadata. HTTP 200 can contain a partial bundle: inspect complete, partial and legs where supplied.' content: application/json: schema: allOf: - $ref: '#/components/schemas/Success' - type: object properties: data: $schema: https://json-schema.org/draft/2020-12/schema $id: https://www.monocrawl.com/schemas/youtube/video-sponsors.json title: youtube/video-sponsors data fields description: Optional data supplied by this operation. Null means unknown. type: object properties: has_paid_promotion: description: Optional has paid promotion supplied by this operation. Null means unknown. type: - boolean - 'null' note: description: Optional note supplied by this operation. Null means unknown. type: - string - 'null' platform: description: Optional platform supplied by this operation. Null means unknown. type: - string - 'null' promo_codes: description: Source array was empty in the reviewed captures; item fields remain unspecified. type: - array - 'null' items: {} sponsors: description: Optional sponsors supplied by this operation. Null means unknown. type: - array - 'null' items: description: Optional record supplied by this operation. Null means unknown. type: - object - 'null' properties: confidence: description: Optional confidence supplied by this operation. Null means unknown. type: - string - 'null' evidence: description: Optional evidence supplied by this operation. Null means unknown. type: - array - 'null' items: description: Optional record supplied by this operation. Null means unknown. type: - object - 'null' properties: {} additionalProperties: true name: description: Optional name supplied by this operation. Null means unknown. type: - string - 'null' website: description: Optional website supplied by this operation. Null means unknown. type: - string - 'null' additionalProperties: true url: description: Original source URL when supplied. type: - string - 'null' video: description: Optional video supplied by this operation. Null means unknown. type: - object - 'null' properties: channel: description: Optional channel supplied by this operation. Null means unknown. type: - object - 'null' properties: handle: description: Optional handle supplied by this operation. Null means unknown. type: - string - 'null' id: description: Source identifier. Preserve the supplied type and exact value. type: - string - 'null' title: description: Source title when supplied. type: - string - 'null' additionalProperties: true id: description: Source identifier. Preserve the supplied type and exact value. type: - string - 'null' title: description: Source title when supplied. type: - string - 'null' additionalProperties: true additionalProperties: true allOf: - anyOf: - required: - has_paid_promotion properties: has_paid_promotion: description: Optional has paid promotion supplied by this operation. Null means unknown. type: - boolean - required: - note properties: note: description: Optional note supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - promo_codes properties: promo_codes: description: Source array was empty in the reviewed captures; item fields remain unspecified. type: - array items: {} - required: - sponsors properties: sponsors: description: Optional sponsors supplied by this operation. Null means unknown. type: - array items: description: Optional record supplied by this operation. Null means unknown. type: - object - 'null' properties: confidence: description: Optional confidence supplied by this operation. Null means unknown. type: - string - 'null' evidence: description: Optional evidence supplied by this operation. Null means unknown. type: - array - 'null' items: description: Optional record supplied by this operation. Null means unknown. type: - object - 'null' properties: {} additionalProperties: true name: description: Optional name supplied by this operation. Null means unknown. type: - string - 'null' website: description: Optional website supplied by this operation. Null means unknown. type: - string - 'null' additionalProperties: true - required: - url properties: url: description: Original source URL when supplied. type: - string minLength: 1 - required: - video properties: video: description: Optional video supplied by this operation. Null means unknown. type: - object properties: channel: description: Optional channel supplied by this operation. Null means unknown. type: - object - 'null' properties: handle: description: Optional handle supplied by this operation. Null means unknown. type: - string - 'null' id: description: Source identifier. Preserve the supplied type and exact value. type: - string - 'null' title: description: Source title when supplied. type: - string - 'null' additionalProperties: true id: description: Source identifier. Preserve the supplied type and exact value. type: - string - 'null' title: description: Source title when supplied. type: - string - 'null' additionalProperties: true x-contract-version: '2026-09-22' x-validation-scope: Required success payload structure; optional fields and source completeness remain separate. examples: - has_paid_promotion: false note: example platform: example promo_codes: [] sponsors: - confidence: example evidence: - {} name: example website: example url: https://example.com/example video: channel: handle: example id: example title: example id: example title: example default: description: The error envelope — the same shape for every non-2xx status. content: application/json: schema: $ref: '#/components/schemas/Error' x-credits: 4 x-production-available: true x-capacity: status: not_assessed message: Capacity is workload-dependent; configured routes do not establish sustained throughput or an availability guarantee. x-availability-scope: Structural check of the effective registered chain, production permission, adapter, configured cost and quality floor without request parameters. True is not a live-health, credential, quota, subscription-entitlement, complete-data or deployment-exposure guarantee. False means no structurally eligible candidate; null means metadata could not establish availability. Composite child capability still depends on its component routes. x-live-proven: true /v1/youtube/video/audio: get: operationId: youtube_video_audio tags: - Youtube summary: YouTube video audio streams description: 'The audio-only streams the platform offers for a video: format tag, direct time-limited link, MIME type, bitrate, sample rate, channels and duration. Links expire; fetch them promptly. Costs 1 credit per successful live response.' parameters: - name: url in: query required: true schema: type: string example: https://www.youtube.com/watch?v=dQw4w9WgXcQ description: Video URL or id - name: dry_run in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: X-Max-Credits in: header required: false schema: type: integer minimum: 0 maximum: 9007199254740991 example: 5 description: Optional credit reservation ceiling for this individual request. Send a non-negative integer in decimal digits. Live execution checks the required reservation after resolving free cache hits or buffered continuation, before charging or calling a supplier. A higher reservation returns HTTP 422 INVALID_PARAMETERS with reason max_credits_exceeded and charges nothing. Invalid header values also return 422. Zero permits only a zero-credit reservation; omitting the header uses normal pricing. dry_run remains a free preview. This does not cap later requests, batches or scheduled runs. security: - ApiKeyHeader: [] - BearerKey: [] responses: '200': description: 'The common success envelope; `data` is endpoint-specific. Many lists use items/count/cursor; bundles use named collections and their documented continuation metadata. HTTP 200 can contain a partial bundle: inspect complete, partial and legs where supplied.' content: application/json: schema: allOf: - $ref: '#/components/schemas/Success' - type: object properties: data: $schema: https://json-schema.org/draft/2020-12/schema $id: https://www.monocrawl.com/schemas/youtube/video/audio.json title: youtube/video/audio data fields description: Optional data supplied by this operation. Null means unknown. type: object properties: count: description: Number of records in this response, not lifetime or total matches. type: - number - 'null' has_more: description: Source continuation indicator; null means unknown. type: - boolean - 'null' items: description: Returned records. Source coverage and completeness vary. type: - array items: description: Optional record supplied by this operation. Null means unknown. type: object properties: audio_channels: description: Optional audio channels supplied by this operation. Null means unknown. type: - number - 'null' audio_quality: description: Optional audio quality supplied by this operation. Null means unknown. type: - string - 'null' audio_sample_rate: description: Optional audio sample rate supplied by this operation. Null means unknown. type: - number - 'null' average_bitrate: description: Optional average bitrate supplied by this operation. Null means unknown. type: - number - 'null' bitrate: description: Optional bitrate supplied by this operation. Null means unknown. type: - number - 'null' content_length: description: Optional content length supplied by this operation. Null means unknown. type: - number - 'null' duration_ms: description: Optional duration ms supplied by this operation. Null means unknown. type: - number - 'null' itag: description: Optional itag supplied by this operation. Null means unknown. type: - number - 'null' last_modified: description: Optional last modified supplied by this operation. Null means unknown. type: - string - 'null' mime_type: description: Optional mime type supplied by this operation. Null means unknown. type: - string - 'null' quality: description: Optional quality supplied by this operation. Null means unknown. type: - string - 'null' url: description: Original source URL when supplied. type: - string - 'null' additionalProperties: true allOf: - anyOf: - required: - audio_channels properties: audio_channels: description: Optional audio channels supplied by this operation. Null means unknown. type: - number - required: - audio_quality properties: audio_quality: description: Optional audio quality supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - audio_sample_rate properties: audio_sample_rate: description: Optional audio sample rate supplied by this operation. Null means unknown. type: - number - required: - average_bitrate properties: average_bitrate: description: Optional average bitrate supplied by this operation. Null means unknown. type: - number - required: - bitrate properties: bitrate: description: Optional bitrate supplied by this operation. Null means unknown. type: - number - required: - content_length properties: content_length: description: Optional content length supplied by this operation. Null means unknown. type: - number - required: - duration_ms properties: duration_ms: description: Optional duration ms supplied by this operation. Null means unknown. type: - number - required: - itag properties: itag: description: Optional itag supplied by this operation. Null means unknown. type: - number - required: - last_modified properties: last_modified: description: Optional last modified supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - mime_type properties: mime_type: description: Optional mime type supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - quality properties: quality: description: Optional quality supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - url properties: url: description: Original source URL when supplied. type: - string minLength: 1 note: description: Optional note supplied by this operation. Null means unknown. type: - string - 'null' url: description: Original source URL when supplied. type: - string - 'null' video_id: description: Optional video id supplied by this operation. Null means unknown. type: - string - 'null' additionalProperties: true required: - items x-contract-version: '2026-09-22' x-validation-scope: Required success payload structure; optional fields and source completeness remain separate. examples: - count: 0 has_more: false items: - audio_channels: 0 audio_quality: example audio_sample_rate: 0 average_bitrate: 0 bitrate: 0 content_length: 0 duration_ms: 0 itag: 0 last_modified: example mime_type: example quality: example url: https://example.com/example note: example url: https://example.com/example video_id: example default: description: The error envelope — the same shape for every non-2xx status. content: application/json: schema: $ref: '#/components/schemas/Error' x-credits: 1 x-production-available: true x-capacity: status: not_assessed message: Capacity is workload-dependent; configured routes do not establish sustained throughput or an availability guarantee. x-availability-scope: Structural check of the effective registered chain, production permission, adapter, configured cost and quality floor without request parameters. True is not a live-health, credential, quota, subscription-entitlement, complete-data or deployment-exposure guarantee. False means no structurally eligible candidate; null means metadata could not establish availability. Composite child capability still depends on its component routes. x-live-proven: true /v1/youtube/video/comment/replies: get: operationId: youtube_video_comment_replies tags: - Youtube summary: YouTube comment replies description: Replies under a specific top-level comment, addressed by the parent comment id. Costs 1 credit per successful live response. parameters: - name: comment_id in: query required: true schema: type: string example: Ugz1234567890AbCdEf4AaABAg description: Top-level (parent) comment id whose replies to fetch. the reference catalogue continuationToken is accepted as this id - name: format in: query required: false schema: type: string enum: - html - plainText example: plainText description: 'html or plainText comment text (maps to textFormat) Accepted values: html, plainText. Case, spaces, hyphens and underscores are interchangeable.' - name: max_results in: query required: false schema: type: string example: '100' description: Requested page size, 1–100. The paid primary defaults to 100; the source may return fewer. Keep an explicit size unchanged while paginating. - name: cursor in: query required: false schema: type: string example: QURTSl9pMg description: Opaque page token from a previous response - name: dry_run in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: judgments in: query required: false schema: type: string enum: - 'on' - 'off' example: 'on' description: 'Add bounded AI labels to eligible returned records (default on). off preserves the original data shape. Unclassified records remain present; labels depend on evidence, time, capacity and the existing request budget. No label surcharge. Accepted values: on, off. Case, spaces, hyphens and underscores are interchangeable.' - name: label in: query required: false schema: type: string enum: - default - none example: none description: 'Set none to disable labels; default enables the endpoint’s label set. Equivalent to judgments=off. Accepted values: default, none. Case, spaces, hyphens and underscores are interchangeable.' - name: label_evidence in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Include exact supporting sentences and zero-based sentence indexes when a label has validated evidence. No extra charge or change to decisions. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: exclude in: query required: false schema: type: string enum: - engagement_bait example: engagement_bait description: 'Optionally remove confidently labelled engagement bait. Uncertain and unclassified records stay; removed IDs and an owner-bound recall reference are returned. Accepted values: engagement_bait. Case, spaces, hyphens and underscores are interchangeable.' - name: fit in: query required: false schema: type: string enum: - goal example: goal description: 'Use goal to replace confidently irrelevant records with recall stubs. Keeps first, last, relevant and uncertain records; preserves order. Full evidence is stored for 24 hours when available. Accepted values: goal. Case, spaces, hyphens and underscores are interchangeable.' - name: goal in: query required: false schema: type: string example: Find concrete product complaints description: 'Required with fit=goal: describe the task in at most 600 characters. Supplied text is task context, never permission to act on posts.' - name: tokens in: query required: false schema: type: string example: '4000' description: Optional soft response target for fit=goal, 256–32000. Safety and evidence retention take priority, so the returned result may exceed it. - name: X-Max-Credits in: header required: false schema: type: integer minimum: 0 maximum: 9007199254740991 example: 5 description: Optional credit reservation ceiling for this individual request. Send a non-negative integer in decimal digits. Live execution checks the required reservation after resolving free cache hits or buffered continuation, before charging or calling a supplier. A higher reservation returns HTTP 422 INVALID_PARAMETERS with reason max_credits_exceeded and charges nothing. Invalid header values also return 422. Zero permits only a zero-credit reservation; omitting the header uses normal pricing. dry_run remains a free preview. This does not cap later requests, batches or scheduled runs. security: - ApiKeyHeader: [] - BearerKey: [] responses: '200': description: 'The common success envelope; `data` is endpoint-specific. Many lists use items/count/cursor; bundles use named collections and their documented continuation metadata. HTTP 200 can contain a partial bundle: inspect complete, partial and legs where supplied.' content: application/json: schema: allOf: - $ref: '#/components/schemas/Success' - type: object properties: data: $schema: https://json-schema.org/draft/2020-12/schema $id: https://www.monocrawl.com/schemas/youtube/video/comment/replies.json title: youtube/video/comment/replies data fields description: Optional data supplied by this operation. Null means unknown. type: object properties: _warnings: description: Source array was empty in the reviewed captures; item fields remain unspecified. type: - array - 'null' items: {} count: description: Number of records in this response, not lifetime or total matches. type: - number - 'null' cursor: description: Opaque next-page token; pass it back unchanged. Null does not prove complete history. type: - string - 'null' dropped: description: Optional dropped supplied by this operation. Null means unknown. type: - number - 'null' has_more: description: Source continuation indicator; null means unknown. type: - boolean - 'null' items: description: Returned records. Source coverage and completeness vary. type: - array items: description: Optional record supplied by this operation. Null means unknown. type: object properties: author: description: Public author information supplied with this record. type: - object - 'null' properties: avatar_url: description: Optional avatar url supplied by this operation. Null means unknown. type: - string - 'null' channel_id: description: Optional channel id supplied by this operation. Null means unknown. type: - string - 'null' channel_url: description: Optional channel url supplied by this operation. Null means unknown. type: - string - 'null' name: description: Optional name supplied by this operation. Null means unknown. type: - string - 'null' additionalProperties: true id: description: Source identifier. Preserve the supplied type and exact value. type: - string - 'null' likes: description: Optional likes supplied by this operation. Null means unknown. type: - number - 'null' parent_id: description: Optional parent id supplied by this operation. Null means unknown. type: - string - 'null' published_at: description: Source publication time when available. type: - string - 'null' text: description: Source text when supplied. type: - string - 'null' text_original: description: Optional text original supplied by this operation. Null means unknown. type: - string - 'null' updated_at: description: Optional updated at supplied by this operation. Null means unknown. type: - string - 'null' additionalProperties: true allOf: - anyOf: - required: - author properties: author: description: Public author information supplied with this record. type: - object properties: avatar_url: description: Optional avatar url supplied by this operation. Null means unknown. type: - string - 'null' channel_id: description: Optional channel id supplied by this operation. Null means unknown. type: - string - 'null' channel_url: description: Optional channel url supplied by this operation. Null means unknown. type: - string - 'null' name: description: Optional name supplied by this operation. Null means unknown. type: - string - 'null' additionalProperties: true - required: - id properties: id: description: Source identifier. Preserve the supplied type and exact value. type: - string minLength: 1 - required: - likes properties: likes: description: Optional likes supplied by this operation. Null means unknown. type: - number - required: - parent_id properties: parent_id: description: Optional parent id supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - published_at properties: published_at: description: Source publication time when available. type: - string minLength: 1 - required: - text properties: text: description: Source text when supplied. type: - string minLength: 1 - required: - text_original properties: text_original: description: Optional text original supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - updated_at properties: updated_at: description: Optional updated at supplied by this operation. Null means unknown. type: - string minLength: 1 parent_id: description: Optional parent id supplied by this operation. Null means unknown. type: - string - 'null' additionalProperties: true required: - items x-contract-version: '2026-09-22' x-validation-scope: Required success payload structure; optional fields and source completeness remain separate. examples: - _warnings: [] count: 0 cursor: null dropped: 0 has_more: false items: - author: avatar_url: https://example.com/example channel_id: example channel_url: https://example.com/example name: example id: example likes: 0 parent_id: example published_at: '2026-09-01T12:00:00Z' text: example text_original: example updated_at: '2026-09-01T12:00:00Z' parent_id: example default: description: The error envelope — the same shape for every non-2xx status. content: application/json: schema: $ref: '#/components/schemas/Error' x-credits: 1 x-production-available: true x-capacity: status: not_assessed message: Capacity is workload-dependent; configured routes do not establish sustained throughput or an availability guarantee. x-availability-scope: Structural check of the effective registered chain, production permission, adapter, configured cost and quality floor without request parameters. True is not a live-health, credential, quota, subscription-entitlement, complete-data or deployment-exposure guarantee. False means no structurally eligible candidate; null means metadata could not establish availability. Composite child capability still depends on its component routes. x-live-proven: true /v1/youtube/video/comments: get: operationId: youtube_video_comments tags: - Youtube summary: YouTube video comments description: Top-level comment threads on a video; comments-disabled videos surface as 404. Costs 1 credit per successful live response. parameters: - name: url in: query required: true schema: type: string example: https://www.youtube.com/watch?v=9bZkp7q19f0 description: Video URL or a bare 11-char video id - name: order in: query required: false schema: type: string enum: - time - relevance example: relevance description: 'time for newest first, or relevance for top comments first Accepted values: time, relevance. Case, spaces, hyphens and underscores are interchangeable.' - name: searchTerm in: query required: false schema: type: string example: great video description: Only comments matching this word or phrase - name: format in: query required: false schema: type: string enum: - html - plainText example: plainText description: 'html or plainText comment text Accepted values: html, plainText. Case, spaces, hyphens and underscores are interchangeable.' - name: max_results in: query required: false schema: type: string example: '100' description: Requested page size, 1–100. The paid primary defaults to 100; the source may return fewer. Keep an explicit size unchanged while paginating. - name: cursor in: query required: false schema: type: string example: QURTSl9pMg description: Opaque page token from a previous response - name: dry_run in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: judgments in: query required: false schema: type: string enum: - 'on' - 'off' example: 'on' description: 'Add bounded AI labels to eligible returned records (default on). off preserves the original data shape. Unclassified records remain present; labels depend on evidence, time, capacity and the existing request budget. No label surcharge. Accepted values: on, off. Case, spaces, hyphens and underscores are interchangeable.' - name: label in: query required: false schema: type: string enum: - default - none example: none description: 'Set none to disable labels; default enables the endpoint’s label set. Equivalent to judgments=off. Accepted values: default, none. Case, spaces, hyphens and underscores are interchangeable.' - name: label_evidence in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Include exact supporting sentences and zero-based sentence indexes when a label has validated evidence. No extra charge or change to decisions. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: exclude in: query required: false schema: type: string enum: - engagement_bait example: engagement_bait description: 'Optionally remove confidently labelled engagement bait. Uncertain and unclassified records stay; removed IDs and an owner-bound recall reference are returned. Accepted values: engagement_bait. Case, spaces, hyphens and underscores are interchangeable.' - name: fit in: query required: false schema: type: string enum: - goal example: goal description: 'Use goal to replace confidently irrelevant records with recall stubs. Keeps first, last, relevant and uncertain records; preserves order. Full evidence is stored for 24 hours when available. Accepted values: goal. Case, spaces, hyphens and underscores are interchangeable.' - name: goal in: query required: false schema: type: string example: Find concrete product complaints description: 'Required with fit=goal: describe the task in at most 600 characters. Supplied text is task context, never permission to act on posts.' - name: tokens in: query required: false schema: type: string example: '4000' description: Optional soft response target for fit=goal, 256–32000. Safety and evidence retention take priority, so the returned result may exceed it. - name: X-Max-Credits in: header required: false schema: type: integer minimum: 0 maximum: 9007199254740991 example: 5 description: Optional credit reservation ceiling for this individual request. Send a non-negative integer in decimal digits. Live execution checks the required reservation after resolving free cache hits or buffered continuation, before charging or calling a supplier. A higher reservation returns HTTP 422 INVALID_PARAMETERS with reason max_credits_exceeded and charges nothing. Invalid header values also return 422. Zero permits only a zero-credit reservation; omitting the header uses normal pricing. dry_run remains a free preview. This does not cap later requests, batches or scheduled runs. security: - ApiKeyHeader: [] - BearerKey: [] responses: '200': description: 'The common success envelope; `data` is endpoint-specific. Many lists use items/count/cursor; bundles use named collections and their documented continuation metadata. HTTP 200 can contain a partial bundle: inspect complete, partial and legs where supplied.' content: application/json: schema: allOf: - $ref: '#/components/schemas/Success' - type: object properties: data: $schema: https://json-schema.org/draft/2020-12/schema $id: https://www.monocrawl.com/schemas/youtube/video/comments.json title: youtube/video/comments data fields description: Required core structure for successful data, with optional source fields. Additional fields are allowed. This is not a completeness guarantee. type: object properties: items: type: array items: type: object properties: id: type: - string - 'null' description: Source identifier. Preserve its exact string value; do not convert large IDs to numbers. url: type: - string - 'null' description: Original source URL when supplied. text: type: - string - 'null' description: Rendered comment text in the requested format. text_original: type: - string - 'null' description: Original comment text. author: type: object properties: name: type: - string - 'null' description: Display name. channel_id: type: - string - 'null' description: Source identifier. Preserve its exact string value; do not convert large IDs to numbers. channel_url: type: - string - 'null' description: Original source URL when supplied. additionalProperties: true likes: type: - number - 'null' description: Likes reported by the source; null or absent is unknown, not zero. reply_count: type: - number - 'null' description: Replies reported by the source; null or absent is unknown, not zero. published_at: type: - string - 'null' description: Source publication time, normalized to an ISO date-time when available. replies: type: array items: type: object properties: id: type: - string - 'null' description: Source identifier. Preserve its exact string value; do not convert large IDs to numbers. text: type: - string - 'null' description: Reply text. parent_id: type: - string - 'null' description: Source identifier. Preserve its exact string value; do not convert large IDs to numbers. additionalProperties: true replies_pagination: type: object properties: returned: type: - number - 'null' description: Included replies reported by the source; null or absent is unknown, not zero. total: type: - number - 'null' description: Reported replies reported by the source; null or absent is unknown, not zero. complete: type: - boolean - 'null' description: Whether the preview contains the reported reply total. has_more: type: - boolean - 'null' description: Whether further replies are reported. additionalProperties: true additionalProperties: true allOf: - anyOf: - required: - id properties: id: type: - string description: Source identifier. Preserve its exact string value; do not convert large IDs to numbers. minLength: 1 - required: - url properties: url: type: - string description: Original source URL when supplied. minLength: 1 - required: - text properties: text: type: - string description: Rendered comment text in the requested format. minLength: 1 - required: - text_original properties: text_original: type: - string description: Original comment text. minLength: 1 - required: - author properties: author: type: object properties: name: type: - string - 'null' description: Display name. channel_id: type: - string - 'null' description: Source identifier. Preserve its exact string value; do not convert large IDs to numbers. channel_url: type: - string - 'null' description: Original source URL when supplied. additionalProperties: true - required: - likes properties: likes: type: - number description: Likes reported by the source; null or absent is unknown, not zero. - required: - reply_count properties: reply_count: type: - number description: Replies reported by the source; null or absent is unknown, not zero. - required: - published_at properties: published_at: type: - string description: Source publication time, normalized to an ISO date-time when available. minLength: 1 - required: - replies properties: replies: type: array items: type: object properties: id: type: - string - 'null' description: Source identifier. Preserve its exact string value; do not convert large IDs to numbers. text: type: - string - 'null' description: Reply text. parent_id: type: - string - 'null' description: Source identifier. Preserve its exact string value; do not convert large IDs to numbers. additionalProperties: true - required: - replies_pagination properties: replies_pagination: type: object properties: returned: type: - number - 'null' description: Included replies reported by the source; null or absent is unknown, not zero. total: type: - number - 'null' description: Reported replies reported by the source; null or absent is unknown, not zero. complete: type: - boolean - 'null' description: Whether the preview contains the reported reply total. has_more: type: - boolean - 'null' description: Whether further replies are reported. additionalProperties: true description: Records in this response page. count: type: - number - 'null' description: Returned row count when supplied; not the full source total. cursor: type: - string - 'null' description: Opaque next-page token. A missing token does not prove full history was retrieved. has_more: type: - boolean - 'null' description: Source continuation indicator; null means unknown. _warnings: type: array items: type: string description: Collection limitations or component warnings. Read before interpreting coverage. total: type: 'null' description: Unknown for this comment-thread listing. Never use the returned page size as the full video comment count. additionalProperties: true required: - items x-contract-version: '2026-09-22' x-validation-scope: Required success payload structure; optional fields and source completeness remain separate. examples: - items: - id: example_comment text: Useful guide likes: 3 reply_count: 2 replies: [] replies_pagination: returned: 0 total: 2 complete: false has_more: true cursor: null has_more: null total: null default: description: The error envelope — the same shape for every non-2xx status. content: application/json: schema: $ref: '#/components/schemas/Error' x-credits: 1 x-production-available: true x-capacity: status: not_assessed message: Capacity is workload-dependent; configured routes do not establish sustained throughput or an availability guarantee. x-availability-scope: Structural check of the effective registered chain, production permission, adapter, configured cost and quality floor without request parameters. True is not a live-health, credential, quota, subscription-entitlement, complete-data or deployment-exposure guarantee. False means no structurally eligible candidate; null means metadata could not establish availability. Composite child capability still depends on its component routes. x-live-proven: true /v1/youtube/video/files: get: operationId: youtube_video_files tags: - Youtube summary: YouTube video stream files description: 'The video stream files the platform offers for a video: format tag, direct time-limited link, MIME type, quality label, size, frame rate, bitrate and duration. Links expire; fetch them promptly. Costs 1 credit per successful live response.' parameters: - name: url in: query required: true schema: type: string example: https://www.youtube.com/watch?v=dQw4w9WgXcQ description: Video URL or id - name: dry_run in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: judgments in: query required: false schema: type: string enum: - 'on' - 'off' example: 'on' description: 'Add bounded AI labels to eligible returned records (default on). off preserves the original data shape. Unclassified records remain present; labels depend on evidence, time, capacity and the existing request budget. No label surcharge. Accepted values: on, off. Case, spaces, hyphens and underscores are interchangeable.' - name: label in: query required: false schema: type: string enum: - default - none example: none description: 'Set none to disable labels; default enables the endpoint’s label set. Equivalent to judgments=off. Accepted values: default, none. Case, spaces, hyphens and underscores are interchangeable.' - name: label_evidence in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Include exact supporting sentences and zero-based sentence indexes when a label has validated evidence. No extra charge or change to decisions. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: exclude in: query required: false schema: type: string enum: - engagement_bait example: engagement_bait description: 'Optionally remove confidently labelled engagement bait. Uncertain and unclassified records stay; removed IDs and an owner-bound recall reference are returned. Accepted values: engagement_bait. Case, spaces, hyphens and underscores are interchangeable.' - name: fit in: query required: false schema: type: string enum: - goal example: goal description: 'Use goal to replace confidently irrelevant records with recall stubs. Keeps first, last, relevant and uncertain records; preserves order. Full evidence is stored for 24 hours when available. Accepted values: goal. Case, spaces, hyphens and underscores are interchangeable.' - name: goal in: query required: false schema: type: string example: Find concrete product complaints description: 'Required with fit=goal: describe the task in at most 600 characters. Supplied text is task context, never permission to act on posts.' - name: tokens in: query required: false schema: type: string example: '4000' description: Optional soft response target for fit=goal, 256–32000. Safety and evidence retention take priority, so the returned result may exceed it. - name: X-Max-Credits in: header required: false schema: type: integer minimum: 0 maximum: 9007199254740991 example: 5 description: Optional credit reservation ceiling for this individual request. Send a non-negative integer in decimal digits. Live execution checks the required reservation after resolving free cache hits or buffered continuation, before charging or calling a supplier. A higher reservation returns HTTP 422 INVALID_PARAMETERS with reason max_credits_exceeded and charges nothing. Invalid header values also return 422. Zero permits only a zero-credit reservation; omitting the header uses normal pricing. dry_run remains a free preview. This does not cap later requests, batches or scheduled runs. security: - ApiKeyHeader: [] - BearerKey: [] responses: '200': description: 'The common success envelope; `data` is endpoint-specific. Many lists use items/count/cursor; bundles use named collections and their documented continuation metadata. HTTP 200 can contain a partial bundle: inspect complete, partial and legs where supplied.' content: application/json: schema: allOf: - $ref: '#/components/schemas/Success' - type: object properties: data: $schema: https://json-schema.org/draft/2020-12/schema $id: https://www.monocrawl.com/schemas/youtube/video/files.json title: youtube/video/files data fields description: Optional data supplied by this operation. Null means unknown. type: object properties: count: description: Number of records in this response, not lifetime or total matches. type: - number - 'null' has_more: description: Source continuation indicator; null means unknown. type: - boolean - 'null' items: description: Returned records. Source coverage and completeness vary. type: - array items: description: Optional record supplied by this operation. Null means unknown. type: object properties: audio_channels: description: Optional audio channels supplied by this operation. Null means unknown. type: - number - 'null' audio_quality: description: Optional audio quality supplied by this operation. Null means unknown. type: - string - 'null' audio_sample_rate: description: Optional audio sample rate supplied by this operation. Null means unknown. type: - number - 'null' average_bitrate: description: Optional average bitrate supplied by this operation. Null means unknown. type: - number - 'null' bitrate: description: Optional bitrate supplied by this operation. Null means unknown. type: - number - 'null' content_length: description: Optional content length supplied by this operation. Null means unknown. type: - number - 'null' duration_ms: description: Optional duration ms supplied by this operation. Null means unknown. type: - number - 'null' fps: description: Optional fps supplied by this operation. Null means unknown. type: - number - 'null' height: description: Optional height supplied by this operation. Null means unknown. type: - number - 'null' itag: description: Optional itag supplied by this operation. Null means unknown. type: - number - 'null' last_modified: description: Optional last modified supplied by this operation. Null means unknown. type: - string - 'null' mime_type: description: Optional mime type supplied by this operation. Null means unknown. type: - string - 'null' quality: description: Optional quality supplied by this operation. Null means unknown. type: - string - 'null' url: description: Original source URL when supplied. type: - string - 'null' width: description: Optional width supplied by this operation. Null means unknown. type: - number - 'null' additionalProperties: true allOf: - anyOf: - required: - audio_channels properties: audio_channels: description: Optional audio channels supplied by this operation. Null means unknown. type: - number - required: - audio_quality properties: audio_quality: description: Optional audio quality supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - audio_sample_rate properties: audio_sample_rate: description: Optional audio sample rate supplied by this operation. Null means unknown. type: - number - required: - average_bitrate properties: average_bitrate: description: Optional average bitrate supplied by this operation. Null means unknown. type: - number - required: - bitrate properties: bitrate: description: Optional bitrate supplied by this operation. Null means unknown. type: - number - required: - content_length properties: content_length: description: Optional content length supplied by this operation. Null means unknown. type: - number - required: - duration_ms properties: duration_ms: description: Optional duration ms supplied by this operation. Null means unknown. type: - number - required: - fps properties: fps: description: Optional fps supplied by this operation. Null means unknown. type: - number - required: - height properties: height: description: Optional height supplied by this operation. Null means unknown. type: - number - required: - itag properties: itag: description: Optional itag supplied by this operation. Null means unknown. type: - number - required: - last_modified properties: last_modified: description: Optional last modified supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - mime_type properties: mime_type: description: Optional mime type supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - quality properties: quality: description: Optional quality supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - url properties: url: description: Original source URL when supplied. type: - string minLength: 1 - required: - width properties: width: description: Optional width supplied by this operation. Null means unknown. type: - number note: description: Optional note supplied by this operation. Null means unknown. type: - string - 'null' url: description: Original source URL when supplied. type: - string - 'null' video_id: description: Optional video id supplied by this operation. Null means unknown. type: - string - 'null' additionalProperties: true required: - items x-contract-version: '2026-09-22' x-validation-scope: Required success payload structure; optional fields and source completeness remain separate. examples: - count: 0 has_more: false items: - audio_channels: 0 audio_quality: example audio_sample_rate: 0 average_bitrate: 0 bitrate: 0 content_length: 0 duration_ms: 0 fps: 0 height: 0 itag: 0 last_modified: example mime_type: example quality: example url: https://example.com/example width: 0 note: example url: https://example.com/example video_id: example default: description: The error envelope — the same shape for every non-2xx status. content: application/json: schema: $ref: '#/components/schemas/Error' x-credits: 1 x-production-available: true x-capacity: status: not_assessed message: Capacity is workload-dependent; configured routes do not establish sustained throughput or an availability guarantee. x-availability-scope: Structural check of the effective registered chain, production permission, adapter, configured cost and quality floor without request parameters. True is not a live-health, credential, quota, subscription-entitlement, complete-data or deployment-exposure guarantee. False means no structurally eligible candidate; null means metadata could not establish availability. Composite child capability still depends on its component routes. x-live-proven: true /v1/youtube/video/subtitles: get: operationId: youtube_video_subtitles tags: - Youtube summary: YouTube caption tracks description: 'The caption tracks a video carries: language code and name, whether auto-generated, and the track link. The transcript text itself is youtube/post-transcript. Costs 1 credit per successful live response.' parameters: - name: url in: query required: true schema: type: string example: https://www.youtube.com/watch?v=dQw4w9WgXcQ description: Video URL or id - name: language in: query required: false schema: type: string example: en description: Restrict to one language code - name: dry_run in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: judgments in: query required: false schema: type: string enum: - 'on' - 'off' example: 'on' description: 'Add bounded AI labels to eligible returned records (default on). off preserves the original data shape. Unclassified records remain present; labels depend on evidence, time, capacity and the existing request budget. No label surcharge. Accepted values: on, off. Case, spaces, hyphens and underscores are interchangeable.' - name: label in: query required: false schema: type: string enum: - default - none example: none description: 'Set none to disable labels; default enables the endpoint’s label set. Equivalent to judgments=off. Accepted values: default, none. Case, spaces, hyphens and underscores are interchangeable.' - name: label_evidence in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Include exact supporting sentences and zero-based sentence indexes when a label has validated evidence. No extra charge or change to decisions. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: exclude in: query required: false schema: type: string enum: - engagement_bait example: engagement_bait description: 'Optionally remove confidently labelled engagement bait. Uncertain and unclassified records stay; removed IDs and an owner-bound recall reference are returned. Accepted values: engagement_bait. Case, spaces, hyphens and underscores are interchangeable.' - name: fit in: query required: false schema: type: string enum: - goal example: goal description: 'Use goal to replace confidently irrelevant records with recall stubs. Keeps first, last, relevant and uncertain records; preserves order. Full evidence is stored for 24 hours when available. Accepted values: goal. Case, spaces, hyphens and underscores are interchangeable.' - name: goal in: query required: false schema: type: string example: Find concrete product complaints description: 'Required with fit=goal: describe the task in at most 600 characters. Supplied text is task context, never permission to act on posts.' - name: tokens in: query required: false schema: type: string example: '4000' description: Optional soft response target for fit=goal, 256–32000. Safety and evidence retention take priority, so the returned result may exceed it. - name: X-Max-Credits in: header required: false schema: type: integer minimum: 0 maximum: 9007199254740991 example: 5 description: Optional credit reservation ceiling for this individual request. Send a non-negative integer in decimal digits. Live execution checks the required reservation after resolving free cache hits or buffered continuation, before charging or calling a supplier. A higher reservation returns HTTP 422 INVALID_PARAMETERS with reason max_credits_exceeded and charges nothing. Invalid header values also return 422. Zero permits only a zero-credit reservation; omitting the header uses normal pricing. dry_run remains a free preview. This does not cap later requests, batches or scheduled runs. security: - ApiKeyHeader: [] - BearerKey: [] responses: '200': description: 'The common success envelope; `data` is endpoint-specific. Many lists use items/count/cursor; bundles use named collections and their documented continuation metadata. HTTP 200 can contain a partial bundle: inspect complete, partial and legs where supplied.' content: application/json: schema: allOf: - $ref: '#/components/schemas/Success' - type: object properties: data: $schema: https://json-schema.org/draft/2020-12/schema $id: https://www.monocrawl.com/schemas/youtube/video/subtitles.json title: youtube/video/subtitles data fields description: Optional data supplied by this operation. Null means unknown. type: object properties: _warnings: description: Optional warnings supplied by this operation. Null means unknown. type: - array - 'null' items: description: Optional record supplied by this operation. Null means unknown. type: - string - 'null' count: description: Number of records in this response, not lifetime or total matches. type: - number - 'null' has_more: description: Source continuation indicator; null means unknown. type: - boolean - 'null' items: description: Returned records. Source coverage and completeness vary. type: - array items: description: Optional record supplied by this operation. Null means unknown. type: object properties: language_code: description: Optional language code supplied by this operation. Null means unknown. type: - string - 'null' language_name: description: Optional language name supplied by this operation. Null means unknown. type: - string - 'null' url: description: Original source URL when supplied. type: - string - 'null' additionalProperties: true allOf: - anyOf: - required: - language_code properties: language_code: description: Optional language code supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - language_name properties: language_name: description: Optional language name supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - url properties: url: description: Original source URL when supplied. type: - string minLength: 1 note: description: Optional note supplied by this operation. Null means unknown. type: - string - 'null' url: description: Original source URL when supplied. type: - string - 'null' video_id: description: Optional video id supplied by this operation. Null means unknown. type: - string - 'null' additionalProperties: true required: - items x-contract-version: '2026-09-22' x-validation-scope: Required success payload structure; optional fields and source completeness remain separate. examples: - _warnings: - example count: 0 has_more: false items: - language_code: example language_name: example url: https://example.com/example note: example url: https://example.com/example video_id: example default: description: The error envelope — the same shape for every non-2xx status. content: application/json: schema: $ref: '#/components/schemas/Error' x-credits: 1 x-production-available: true x-capacity: status: not_assessed message: Capacity is workload-dependent; configured routes do not establish sustained throughput or an availability guarantee. x-availability-scope: Structural check of the effective registered chain, production permission, adapter, configured cost and quality floor without request parameters. True is not a live-health, credential, quota, subscription-entitlement, complete-data or deployment-exposure guarantee. False means no structurally eligible candidate; null means metadata could not establish availability. Composite child capability still depends on its component routes. x-live-proven: true /v1/youtube/video/thumbnails: get: operationId: youtube_video_thumbnails tags: - Youtube summary: YouTube video thumbnails description: A video's thumbnail set from the snippet, plus conventional i.ytimg.com URLs for every size. Costs 1 credit per successful live response. parameters: - name: url in: query required: true schema: type: string example: https://www.youtube.com/watch?v=9bZkp7q19f0 description: Video URL or a bare 11-char video id - name: dry_run in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: judgments in: query required: false schema: type: string enum: - 'on' - 'off' example: 'on' description: 'Add bounded AI labels to eligible returned records (default on). off preserves the original data shape. Unclassified records remain present; labels depend on evidence, time, capacity and the existing request budget. No label surcharge. Accepted values: on, off. Case, spaces, hyphens and underscores are interchangeable.' - name: label in: query required: false schema: type: string enum: - default - none example: none description: 'Set none to disable labels; default enables the endpoint’s label set. Equivalent to judgments=off. Accepted values: default, none. Case, spaces, hyphens and underscores are interchangeable.' - name: label_evidence in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Include exact supporting sentences and zero-based sentence indexes when a label has validated evidence. No extra charge or change to decisions. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: exclude in: query required: false schema: type: string enum: - engagement_bait example: engagement_bait description: 'Optionally remove confidently labelled engagement bait. Uncertain and unclassified records stay; removed IDs and an owner-bound recall reference are returned. Accepted values: engagement_bait. Case, spaces, hyphens and underscores are interchangeable.' - name: fit in: query required: false schema: type: string enum: - goal example: goal description: 'Use goal to replace confidently irrelevant records with recall stubs. Keeps first, last, relevant and uncertain records; preserves order. Full evidence is stored for 24 hours when available. Accepted values: goal. Case, spaces, hyphens and underscores are interchangeable.' - name: goal in: query required: false schema: type: string example: Find concrete product complaints description: 'Required with fit=goal: describe the task in at most 600 characters. Supplied text is task context, never permission to act on posts.' - name: tokens in: query required: false schema: type: string example: '4000' description: Optional soft response target for fit=goal, 256–32000. Safety and evidence retention take priority, so the returned result may exceed it. - name: X-Max-Credits in: header required: false schema: type: integer minimum: 0 maximum: 9007199254740991 example: 5 description: Optional credit reservation ceiling for this individual request. Send a non-negative integer in decimal digits. Live execution checks the required reservation after resolving free cache hits or buffered continuation, before charging or calling a supplier. A higher reservation returns HTTP 422 INVALID_PARAMETERS with reason max_credits_exceeded and charges nothing. Invalid header values also return 422. Zero permits only a zero-credit reservation; omitting the header uses normal pricing. dry_run remains a free preview. This does not cap later requests, batches or scheduled runs. security: - ApiKeyHeader: [] - BearerKey: [] responses: '200': description: 'The common success envelope; `data` is endpoint-specific. Many lists use items/count/cursor; bundles use named collections and their documented continuation metadata. HTTP 200 can contain a partial bundle: inspect complete, partial and legs where supplied.' content: application/json: schema: allOf: - $ref: '#/components/schemas/Success' - type: object properties: data: $schema: https://json-schema.org/draft/2020-12/schema $id: https://www.monocrawl.com/schemas/youtube/video/thumbnails.json title: youtube/video/thumbnails data fields description: Optional data supplied by this operation. Null means unknown. type: object properties: _warnings: description: Optional warnings supplied by this operation. Null means unknown. type: - array - 'null' items: description: Optional record supplied by this operation. Null means unknown. type: - string - 'null' best_url: description: Optional best url supplied by this operation. Null means unknown. type: - string - 'null' derived_urls: description: Optional derived urls supplied by this operation. Null means unknown. type: - object - 'null' properties: default: description: Optional default supplied by this operation. Null means unknown. type: - string - 'null' high: description: Optional high supplied by this operation. Null means unknown. type: - string - 'null' maxres: description: Optional maxres supplied by this operation. Null means unknown. type: - string - 'null' medium: description: Optional medium supplied by this operation. Null means unknown. type: - string - 'null' standard: description: Optional standard supplied by this operation. Null means unknown. type: - string - 'null' additionalProperties: true thumbnails: description: Optional thumbnails supplied by this operation. Null means unknown. type: - object - 'null' properties: default: description: Optional default supplied by this operation. Null means unknown. type: - object - 'null' properties: height: description: Optional height supplied by this operation. Null means unknown. type: - number - 'null' url: description: Original source URL when supplied. type: - string - 'null' width: description: Optional width supplied by this operation. Null means unknown. type: - number - 'null' additionalProperties: true high: description: Optional high supplied by this operation. Null means unknown. type: - object - 'null' properties: height: description: Optional height supplied by this operation. Null means unknown. type: - number - 'null' url: description: Original source URL when supplied. type: - string - 'null' width: description: Optional width supplied by this operation. Null means unknown. type: - number - 'null' additionalProperties: true maxres: description: Optional maxres supplied by this operation. Null means unknown. type: - object - 'null' properties: height: description: Optional height supplied by this operation. Null means unknown. type: - number - 'null' url: description: Original source URL when supplied. type: - string - 'null' width: description: Optional width supplied by this operation. Null means unknown. type: - number - 'null' additionalProperties: true medium: description: Optional medium supplied by this operation. Null means unknown. type: - object - 'null' properties: height: description: Optional height supplied by this operation. Null means unknown. type: - number - 'null' url: description: Original source URL when supplied. type: - string - 'null' width: description: Optional width supplied by this operation. Null means unknown. type: - number - 'null' additionalProperties: true standard: description: Optional standard supplied by this operation. Null means unknown. type: - object - 'null' properties: height: description: Optional height supplied by this operation. Null means unknown. type: - number - 'null' url: description: Original source URL when supplied. type: - string - 'null' width: description: Optional width supplied by this operation. Null means unknown. type: - number - 'null' additionalProperties: true additionalProperties: true title: description: Source title when supplied. type: - string - 'null' video_id: description: Optional video id supplied by this operation. Null means unknown. type: - string - 'null' additionalProperties: true allOf: - anyOf: - required: - best_url properties: best_url: description: Optional best url supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - derived_urls properties: derived_urls: description: Optional derived urls supplied by this operation. Null means unknown. type: - object properties: default: description: Optional default supplied by this operation. Null means unknown. type: - string - 'null' high: description: Optional high supplied by this operation. Null means unknown. type: - string - 'null' maxres: description: Optional maxres supplied by this operation. Null means unknown. type: - string - 'null' medium: description: Optional medium supplied by this operation. Null means unknown. type: - string - 'null' standard: description: Optional standard supplied by this operation. Null means unknown. type: - string - 'null' additionalProperties: true - required: - thumbnails properties: thumbnails: description: Optional thumbnails supplied by this operation. Null means unknown. type: - object properties: default: description: Optional default supplied by this operation. Null means unknown. type: - object - 'null' properties: height: description: Optional height supplied by this operation. Null means unknown. type: - number - 'null' url: description: Original source URL when supplied. type: - string - 'null' width: description: Optional width supplied by this operation. Null means unknown. type: - number - 'null' additionalProperties: true high: description: Optional high supplied by this operation. Null means unknown. type: - object - 'null' properties: height: description: Optional height supplied by this operation. Null means unknown. type: - number - 'null' url: description: Original source URL when supplied. type: - string - 'null' width: description: Optional width supplied by this operation. Null means unknown. type: - number - 'null' additionalProperties: true maxres: description: Optional maxres supplied by this operation. Null means unknown. type: - object - 'null' properties: height: description: Optional height supplied by this operation. Null means unknown. type: - number - 'null' url: description: Original source URL when supplied. type: - string - 'null' width: description: Optional width supplied by this operation. Null means unknown. type: - number - 'null' additionalProperties: true medium: description: Optional medium supplied by this operation. Null means unknown. type: - object - 'null' properties: height: description: Optional height supplied by this operation. Null means unknown. type: - number - 'null' url: description: Original source URL when supplied. type: - string - 'null' width: description: Optional width supplied by this operation. Null means unknown. type: - number - 'null' additionalProperties: true standard: description: Optional standard supplied by this operation. Null means unknown. type: - object - 'null' properties: height: description: Optional height supplied by this operation. Null means unknown. type: - number - 'null' url: description: Original source URL when supplied. type: - string - 'null' width: description: Optional width supplied by this operation. Null means unknown. type: - number - 'null' additionalProperties: true additionalProperties: true - required: - title properties: title: description: Source title when supplied. type: - string minLength: 1 - required: - video_id properties: video_id: description: Optional video id supplied by this operation. Null means unknown. type: - string minLength: 1 x-contract-version: '2026-09-22' x-validation-scope: Required success payload structure; optional fields and source completeness remain separate. examples: - _warnings: - example best_url: https://example.com/example derived_urls: default: example high: example maxres: example medium: example standard: example thumbnails: default: height: 0 url: https://example.com/example width: 0 high: height: 0 url: https://example.com/example width: 0 maxres: height: 0 url: https://example.com/example width: 0 medium: height: 0 url: https://example.com/example width: 0 standard: height: 0 url: https://example.com/example width: 0 title: example video_id: example default: description: The error envelope — the same shape for every non-2xx status. content: application/json: schema: $ref: '#/components/schemas/Error' x-credits: 1 x-production-available: true x-capacity: status: not_assessed message: Capacity is workload-dependent; configured routes do not establish sustained throughput or an availability guarantee. x-availability-scope: Structural check of the effective registered chain, production permission, adapter, configured cost and quality floor without request parameters. True is not a live-health, credential, quota, subscription-entitlement, complete-data or deployment-exposure guarantee. False means no structurally eligible candidate; null means metadata could not establish availability. Composite child capability still depends on its component routes. x-live-proven: true /v1/youtube/videos: get: operationId: youtube_videos tags: - Youtube summary: YouTube videos (batch) description: Batch video lookup — one normalized record per id; unknown/private/deleted ids are reported in `missing`. Costs 2 credits per successful live response. parameters: - name: ids in: query required: true schema: type: string example: 9bZkp7q19f0,kJQP7kiw5Fk description: Comma-separated (or JSON array of) video ids or URLs; up to 250, chunked 50 per upstream call - name: hl in: query required: false schema: type: string example: en description: BCP-47 language for localized snippet text - name: dry_run in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: judgments in: query required: false schema: type: string enum: - 'on' - 'off' example: 'on' description: 'Add bounded AI labels to eligible returned records (default on). off preserves the original data shape. Unclassified records remain present; labels depend on evidence, time, capacity and the existing request budget. No label surcharge. Accepted values: on, off. Case, spaces, hyphens and underscores are interchangeable.' - name: label in: query required: false schema: type: string enum: - default - none example: none description: 'Set none to disable labels; default enables the endpoint’s label set. Equivalent to judgments=off. Accepted values: default, none. Case, spaces, hyphens and underscores are interchangeable.' - name: label_evidence in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Include exact supporting sentences and zero-based sentence indexes when a label has validated evidence. No extra charge or change to decisions. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: exclude in: query required: false schema: type: string enum: - engagement_bait example: engagement_bait description: 'Optionally remove confidently labelled engagement bait. Uncertain and unclassified records stay; removed IDs and an owner-bound recall reference are returned. Accepted values: engagement_bait. Case, spaces, hyphens and underscores are interchangeable.' - name: fit in: query required: false schema: type: string enum: - goal example: goal description: 'Use goal to replace confidently irrelevant records with recall stubs. Keeps first, last, relevant and uncertain records; preserves order. Full evidence is stored for 24 hours when available. Accepted values: goal. Case, spaces, hyphens and underscores are interchangeable.' - name: goal in: query required: false schema: type: string example: Find concrete product complaints description: 'Required with fit=goal: describe the task in at most 600 characters. Supplied text is task context, never permission to act on posts.' - name: tokens in: query required: false schema: type: string example: '4000' description: Optional soft response target for fit=goal, 256–32000. Safety and evidence retention take priority, so the returned result may exceed it. - name: X-Max-Credits in: header required: false schema: type: integer minimum: 0 maximum: 9007199254740991 example: 5 description: Optional credit reservation ceiling for this individual request. Send a non-negative integer in decimal digits. Live execution checks the required reservation after resolving free cache hits or buffered continuation, before charging or calling a supplier. A higher reservation returns HTTP 422 INVALID_PARAMETERS with reason max_credits_exceeded and charges nothing. Invalid header values also return 422. Zero permits only a zero-credit reservation; omitting the header uses normal pricing. dry_run remains a free preview. This does not cap later requests, batches or scheduled runs. security: - ApiKeyHeader: [] - BearerKey: [] responses: '200': description: 'The common success envelope; `data` is endpoint-specific. Many lists use items/count/cursor; bundles use named collections and their documented continuation metadata. HTTP 200 can contain a partial bundle: inspect complete, partial and legs where supplied.' content: application/json: schema: allOf: - $ref: '#/components/schemas/Success' - type: object properties: data: $schema: https://json-schema.org/draft/2020-12/schema $id: https://www.monocrawl.com/schemas/youtube/videos.json title: youtube/videos data fields description: Required core structure for successful data, with optional source fields. Additional fields are allowed. This is not a completeness guarantee. type: object properties: items: type: array items: type: object properties: id: type: - string - 'null' description: Source identifier. Preserve its exact string value; do not convert large IDs to numbers. url: type: - string - 'null' description: Original source URL when supplied. title: type: - string - 'null' description: Video title. description: type: - string - 'null' description: Video description. published_at: type: - string - 'null' description: Source publication time, normalized to an ISO date-time when available. duration_seconds: type: - number - 'null' description: Duration in seconds. channel: type: object properties: id: type: - string - 'null' description: Source identifier. Preserve its exact string value; do not convert large IDs to numbers. name: type: - string - 'null' description: Channel display name. url: type: - string - 'null' description: Original source URL when supplied. additionalProperties: true views: type: - number - 'null' description: Views reported by the source; null or absent is unknown, not zero. likes: type: - number - 'null' description: Likes reported by the source; null or absent is unknown, not zero. comments_count: type: - number - 'null' description: Comments reported by the source; null or absent is unknown, not zero. additionalProperties: true allOf: - anyOf: - required: - id properties: id: type: - string description: Source identifier. Preserve its exact string value; do not convert large IDs to numbers. minLength: 1 - required: - url properties: url: type: - string description: Original source URL when supplied. minLength: 1 - required: - title properties: title: type: - string description: Video title. minLength: 1 - required: - description properties: description: type: - string description: Video description. minLength: 1 - required: - published_at properties: published_at: type: - string description: Source publication time, normalized to an ISO date-time when available. minLength: 1 - required: - duration_seconds properties: duration_seconds: type: - number description: Duration in seconds. - required: - channel properties: channel: type: object properties: id: type: - string - 'null' description: Source identifier. Preserve its exact string value; do not convert large IDs to numbers. name: type: - string - 'null' description: Channel display name. url: type: - string - 'null' description: Original source URL when supplied. additionalProperties: true - required: - views properties: views: type: - number description: Views reported by the source; null or absent is unknown, not zero. - required: - likes properties: likes: type: - number description: Likes reported by the source; null or absent is unknown, not zero. - required: - comments_count properties: comments_count: type: - number description: Comments reported by the source; null or absent is unknown, not zero. description: Records in this response page. count: type: - number - 'null' description: Returned row count when supplied; not the full source total. cursor: type: - string - 'null' description: Opaque next-page token. A missing token does not prove full history was retrieved. has_more: type: - boolean - 'null' description: Source continuation indicator; null means unknown. _warnings: type: array items: type: string description: Collection limitations or component warnings. Read before interpreting coverage. additionalProperties: true required: - items x-contract-version: '2026-09-22' x-validation-scope: Required success payload structure; optional fields and source completeness remain separate. examples: - items: - id: abcdefghijk title: A quieter desk setup published_at: '2026-09-01T12:00:00Z' channel: id: UC_example name: Example Channel duration_seconds: 482 views: 12600 likes: 640 comments_count: 38 cursor: null has_more: null default: description: The error envelope — the same shape for every non-2xx status. content: application/json: schema: $ref: '#/components/schemas/Error' x-credits: 2 x-production-available: true x-capacity: status: not_assessed message: Capacity is workload-dependent; configured routes do not establish sustained throughput or an availability guarantee. x-availability-scope: Structural check of the effective registered chain, production permission, adapter, configured cost and quality floor without request parameters. True is not a live-health, credential, quota, subscription-entitlement, complete-data or deployment-exposure guarantee. False means no structurally eligible candidate; null means metadata could not establish availability. Composite child capability still depends on its component routes. x-live-proven: true /v1/youtube/videos/trending: get: operationId: youtube_videos_trending tags: - Youtube summary: YouTube trending videos description: The most-popular videos chart (videos.list chart=mostPopular) for a region and optional category. Costs 1 credit per successful live response. parameters: - name: region in: query required: false schema: type: string example: US description: ISO-3166 region code (default US; maps to regionCode) - name: category in: query required: false schema: type: string example: '10' description: videoCategoryId to restrict the chart - name: language in: query required: false schema: type: string example: en description: Localized text language (maps to hl) - name: max_results in: query required: false schema: type: string example: '50' description: Requested page size, 1–50. The paid primary defaults to 50; the source may return fewer. Keep an explicit size unchanged while paginating. - name: cursor in: query required: false schema: type: string example: CAUQAA description: Opaque page token from a previous response - name: dry_run in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: judgments in: query required: false schema: type: string enum: - 'on' - 'off' example: 'on' description: 'Add bounded AI labels to eligible returned records (default on). off preserves the original data shape. Unclassified records remain present; labels depend on evidence, time, capacity and the existing request budget. No label surcharge. Accepted values: on, off. Case, spaces, hyphens and underscores are interchangeable.' - name: label in: query required: false schema: type: string enum: - default - none example: none description: 'Set none to disable labels; default enables the endpoint’s label set. Equivalent to judgments=off. Accepted values: default, none. Case, spaces, hyphens and underscores are interchangeable.' - name: label_evidence in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Include exact supporting sentences and zero-based sentence indexes when a label has validated evidence. No extra charge or change to decisions. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: exclude in: query required: false schema: type: string enum: - engagement_bait example: engagement_bait description: 'Optionally remove confidently labelled engagement bait. Uncertain and unclassified records stay; removed IDs and an owner-bound recall reference are returned. Accepted values: engagement_bait. Case, spaces, hyphens and underscores are interchangeable.' - name: fit in: query required: false schema: type: string enum: - goal example: goal description: 'Use goal to replace confidently irrelevant records with recall stubs. Keeps first, last, relevant and uncertain records; preserves order. Full evidence is stored for 24 hours when available. Accepted values: goal. Case, spaces, hyphens and underscores are interchangeable.' - name: goal in: query required: false schema: type: string example: Find concrete product complaints description: 'Required with fit=goal: describe the task in at most 600 characters. Supplied text is task context, never permission to act on posts.' - name: tokens in: query required: false schema: type: string example: '4000' description: Optional soft response target for fit=goal, 256–32000. Safety and evidence retention take priority, so the returned result may exceed it. - name: X-Max-Credits in: header required: false schema: type: integer minimum: 0 maximum: 9007199254740991 example: 5 description: Optional credit reservation ceiling for this individual request. Send a non-negative integer in decimal digits. Live execution checks the required reservation after resolving free cache hits or buffered continuation, before charging or calling a supplier. A higher reservation returns HTTP 422 INVALID_PARAMETERS with reason max_credits_exceeded and charges nothing. Invalid header values also return 422. Zero permits only a zero-credit reservation; omitting the header uses normal pricing. dry_run remains a free preview. This does not cap later requests, batches or scheduled runs. security: - ApiKeyHeader: [] - BearerKey: [] responses: '200': description: 'The common success envelope; `data` is endpoint-specific. Many lists use items/count/cursor; bundles use named collections and their documented continuation metadata. HTTP 200 can contain a partial bundle: inspect complete, partial and legs where supplied.' content: application/json: schema: allOf: - $ref: '#/components/schemas/Success' - type: object properties: data: $schema: https://json-schema.org/draft/2020-12/schema $id: https://www.monocrawl.com/schemas/youtube/videos/trending.json title: youtube/videos/trending data fields description: Optional data supplied by this operation. Null means unknown. type: object properties: _warnings: description: Optional warnings supplied by this operation. Null means unknown. type: - array - 'null' items: description: Optional record supplied by this operation. Null means unknown. type: - string - 'null' count: description: Number of records in this response, not lifetime or total matches. type: - number - 'null' cursor: description: Opaque next-page token; pass it back unchanged. Null does not prove complete history. type: - string - 'null' dropped: description: Optional dropped supplied by this operation. Null means unknown. type: - number - 'null' has_more: description: Source continuation indicator; null means unknown. type: - boolean - 'null' items: description: Returned records. Source coverage and completeness vary. type: - array items: description: Optional record supplied by this operation. Null means unknown. type: object properties: category_id: description: Optional category id supplied by this operation. Null means unknown. type: - string - 'null' channel: description: Optional channel supplied by this operation. Null means unknown. type: - object - 'null' properties: id: description: Source identifier. Preserve the supplied type and exact value. type: - string - 'null' name: description: Optional name supplied by this operation. Null means unknown. type: - string - 'null' url: description: Original source URL when supplied. type: - string - 'null' additionalProperties: true comments_count: description: Optional comments count supplied by this operation. Null means unknown. type: - number - 'null' default_language: description: Optional default language supplied by this operation. Null means unknown. type: - string - 'null' definition: description: Optional definition supplied by this operation. Null means unknown. type: - string - 'null' description: description: Source description; null or absent means not supplied. type: - string - 'null' dimension: description: Optional dimension supplied by this operation. Null means unknown. type: - string - 'null' duration: description: Optional duration supplied by this operation. Null means unknown. type: - string - 'null' duration_seconds: description: Optional duration seconds supplied by this operation. Null means unknown. type: - number - 'null' embeddable: description: Optional embeddable supplied by this operation. Null means unknown. type: - boolean - 'null' favorites: description: Optional favorites supplied by this operation. Null means unknown. type: - number - 'null' has_captions: description: Optional has captions supplied by this operation. Null means unknown. type: - boolean - 'null' id: description: Source identifier. Preserve the supplied type and exact value. type: - string - 'null' licensed_content: description: Optional licensed content supplied by this operation. Null means unknown. type: - boolean - 'null' likes: description: Optional likes supplied by this operation. Null means unknown. type: - number - 'null' live_broadcast_content: description: Optional live broadcast content supplied by this operation. Null means unknown. type: - string - 'null' made_for_kids: description: Optional made for kids supplied by this operation. Null means unknown. type: - boolean - 'null' privacy_status: description: Optional privacy status supplied by this operation. Null means unknown. type: - string - 'null' projection: description: Optional projection supplied by this operation. Null means unknown. type: - string - 'null' published_at: description: Source publication time when available. type: - string - 'null' tags: description: Optional tags supplied by this operation. Null means unknown. type: - array - 'null' items: description: Optional record supplied by this operation. Null means unknown. type: - string - 'null' thumbnails: description: Optional thumbnails supplied by this operation. Null means unknown. type: - object - 'null' properties: default: description: Optional default supplied by this operation. Null means unknown. type: - object - 'null' properties: {} additionalProperties: true fhd: description: Optional fhd supplied by this operation. Null means unknown. type: - object - 'null' properties: {} additionalProperties: true high: description: Optional high supplied by this operation. Null means unknown. type: - object - 'null' properties: {} additionalProperties: true maxres: description: Optional maxres supplied by this operation. Null means unknown. type: - object - 'null' properties: {} additionalProperties: true medium: description: Optional medium supplied by this operation. Null means unknown. type: - object - 'null' properties: {} additionalProperties: true qhd: description: Optional qhd supplied by this operation. Null means unknown. type: - object - 'null' properties: {} additionalProperties: true standard: description: Optional standard supplied by this operation. Null means unknown. type: - object - 'null' properties: {} additionalProperties: true uhd: description: Optional uhd supplied by this operation. Null means unknown. type: - object - 'null' properties: {} additionalProperties: true additionalProperties: true title: description: Source title when supplied. type: - string - 'null' url: description: Original source URL when supplied. type: - string - 'null' views: description: Optional views supplied by this operation. Null means unknown. type: - number - 'null' additionalProperties: true allOf: - anyOf: - required: - category_id properties: category_id: description: Optional category id supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - channel properties: channel: description: Optional channel supplied by this operation. Null means unknown. type: - object properties: id: description: Source identifier. Preserve the supplied type and exact value. type: - string - 'null' name: description: Optional name supplied by this operation. Null means unknown. type: - string - 'null' url: description: Original source URL when supplied. type: - string - 'null' additionalProperties: true - required: - comments_count properties: comments_count: description: Optional comments count supplied by this operation. Null means unknown. type: - number - required: - default_language properties: default_language: description: Optional default language supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - definition properties: definition: description: Optional definition supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - description properties: description: description: Source description; null or absent means not supplied. type: - string minLength: 1 - required: - dimension properties: dimension: description: Optional dimension supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - duration properties: duration: description: Optional duration supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - duration_seconds properties: duration_seconds: description: Optional duration seconds supplied by this operation. Null means unknown. type: - number - required: - embeddable properties: embeddable: description: Optional embeddable supplied by this operation. Null means unknown. type: - boolean - required: - favorites properties: favorites: description: Optional favorites supplied by this operation. Null means unknown. type: - number - required: - has_captions properties: has_captions: description: Optional has captions supplied by this operation. Null means unknown. type: - boolean - required: - id properties: id: description: Source identifier. Preserve the supplied type and exact value. type: - string minLength: 1 - required: - licensed_content properties: licensed_content: description: Optional licensed content supplied by this operation. Null means unknown. type: - boolean - required: - likes properties: likes: description: Optional likes supplied by this operation. Null means unknown. type: - number - required: - live_broadcast_content properties: live_broadcast_content: description: Optional live broadcast content supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - made_for_kids properties: made_for_kids: description: Optional made for kids supplied by this operation. Null means unknown. type: - boolean - required: - privacy_status properties: privacy_status: description: Optional privacy status supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - projection properties: projection: description: Optional projection supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - published_at properties: published_at: description: Source publication time when available. type: - string minLength: 1 - required: - tags properties: tags: description: Optional tags supplied by this operation. Null means unknown. type: - array items: description: Optional record supplied by this operation. Null means unknown. type: - string - 'null' - required: - thumbnails properties: thumbnails: description: Optional thumbnails supplied by this operation. Null means unknown. type: - object properties: default: description: Optional default supplied by this operation. Null means unknown. type: - object - 'null' properties: {} additionalProperties: true fhd: description: Optional fhd supplied by this operation. Null means unknown. type: - object - 'null' properties: {} additionalProperties: true high: description: Optional high supplied by this operation. Null means unknown. type: - object - 'null' properties: {} additionalProperties: true maxres: description: Optional maxres supplied by this operation. Null means unknown. type: - object - 'null' properties: {} additionalProperties: true medium: description: Optional medium supplied by this operation. Null means unknown. type: - object - 'null' properties: {} additionalProperties: true qhd: description: Optional qhd supplied by this operation. Null means unknown. type: - object - 'null' properties: {} additionalProperties: true standard: description: Optional standard supplied by this operation. Null means unknown. type: - object - 'null' properties: {} additionalProperties: true uhd: description: Optional uhd supplied by this operation. Null means unknown. type: - object - 'null' properties: {} additionalProperties: true additionalProperties: true - required: - title properties: title: description: Source title when supplied. type: - string minLength: 1 - required: - url properties: url: description: Original source URL when supplied. type: - string minLength: 1 - required: - views properties: views: description: Optional views supplied by this operation. Null means unknown. type: - number region: description: Optional region supplied by this operation. Null means unknown. type: - string - 'null' total: description: Source-reported total; null is unknown. type: - number - 'null' additionalProperties: true required: - items x-contract-version: '2026-09-22' x-validation-scope: Required success payload structure; optional fields and source completeness remain separate. examples: - _warnings: - example count: 0 cursor: null dropped: 0 has_more: false items: - category_id: example channel: id: example name: example url: https://example.com/example comments_count: 0 default_language: example definition: example description: example dimension: example duration: example duration_seconds: 0 embeddable: false favorites: 0 has_captions: false id: example licensed_content: false likes: 0 live_broadcast_content: example made_for_kids: false privacy_status: example projection: example published_at: '2026-09-01T12:00:00Z' tags: - example thumbnails: default: {} fhd: {} high: {} maxres: {} medium: {} qhd: {} standard: {} uhd: {} title: example url: https://example.com/example views: 0 region: example total: 0 default: description: The error envelope — the same shape for every non-2xx status. content: application/json: schema: $ref: '#/components/schemas/Error' x-credits: 1 x-production-available: true x-capacity: status: not_assessed message: Capacity is workload-dependent; configured routes do not establish sustained throughput or an availability guarantee. x-availability-scope: Structural check of the effective registered chain, production permission, adapter, configured cost and quality floor without request parameters. True is not a live-health, credential, quota, subscription-entitlement, complete-data or deployment-exposure guarantee. False means no structurally eligible candidate; null means metadata could not establish availability. Composite child capability still depends on its component routes. x-live-proven: true components: schemas: Error: type: object required: - success - error - credits_used - request_id properties: success: const: false error: type: object required: - type - message - status properties: type: type: string enum: - UNAUTHORIZED - KEY_REVOKED - KEY_LIMIT_EXCEEDED - RATE_LIMITED - INSUFFICIENT_CREDITS - RESOURCE_NOT_FOUND - INVALID_PARAMETERS - TARGET_ACCESS_DENIED - UPSTREAM_ERROR - UPSTREAM_TIMEOUT - FREE_CAPACITY_UNAVAILABLE - CAPACITY_UNAVAILABLE - ENDPOINT_NOT_FOUND - ENDPOINT_NOT_AVAILABLE - FAIR_USE_EXCEEDED - INTERNAL_ERROR message: type: string status: type: integer doc_url: type: string description: Deep link to the exact section of the errors guide for this type. details: type: object credits_used: type: - integer - 'null' description: Confirmed net charge; null when billing is pending reconciliation. Inspect error.details.billing_status and retain request_id. credits_remaining: type: integer request_id: type: string Success: type: object required: - success - platform - endpoint - data - credits_used - credits_remaining - request_id properties: _completeness: type: object description: Reported response completeness, not a guarantee of complete platform history. Missing source assertions remain unknown. properties: state: type: string enum: - complete - partial - unknown scope: type: string inspection_limited: type: boolean success: const: true platform: type: string endpoint: type: string description: The resolved path, e.g. `/v1/github/profile`. data: description: Amazon responses include marketplace.country and marketplace.domain (resolved request marketplace, UK by default). X profiles preserve location, bio_link and cover_url when supplied. TikTok profiles preserve commerce_user, seller, region, location and business_category when supplied; region identifies the account region rather than personal residence. TikTok comments use platform_default selection, which can change between fetches; keep the same video and options when following cursors. Amazon review variant is readable text. Facebook profiles preserve cover_url, following and created_at when supplied; likes_count and followers are distinct and follower totals may be rounded. Endpoint-specific normalized payload, not one universal post/profile schema. Many lists use items/count/cursor; a null cursor means no usable next cursor was supplied, not proof that all history was retrieved. Check has_more and warnings where present. Social full-profile bundles use posts_cursor and posts_pagination.next_params; retain all returned next parameters. YouTube channel bundles instead use recent_videos, cursor and recent_videos_pagination. Inspect complete/partial/legs where supplied for bounded or failed components. Optional model-derived fields are labelled, not source facts. credits_used: type: integer credits_remaining: type: integer request_id: type: string cached: type: boolean stale: type: boolean description: True only for an explicitly labelled, zero-credit reference snapshot served after a temporary upstream failure. age_seconds: type: integer minimum: 0 description: Age of a stale snapshot since its original retrieval; not reset by outage recovery. fetched_at: type: string format: date-time description: Original retrieval time of a stale snapshot, in UTC. synthetic: type: boolean description: Present and true only on the explicitly requested /sandbox surface. Synthetic responses are representative and charged 0 credits; production /v1 never returns them. degraded: type: boolean description: Reserved for sandbox compatibility. Production /v1 reports upstream failure as an error and never serves a representative fallback. securitySchemes: ApiKeyHeader: type: apiKey in: header name: x-api-key description: Your API key (`mn_…`), from the console. The recommended style. BearerKey: type: http scheme: bearer description: The same key as a Bearer token, for clients that only expose an Authorization field. Keys are never accepted in the query string — URLs leak into logs and referrers. x-provenance: method: harvested publisher: Monocrawl source: https://www.monocrawl.com/openapi.json note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json); stamped by stamp-openapi-provenance.py (roadmap#793)