> ## Documentation Index > Fetch the complete documentation index at: https://docs.mentionlab.io/llms.txt > Use this file to discover all available pages before exploring further. # List YouTube videos cited in scope > Returns a paginated list of YouTube videos cited by AI responses in the selected scope, with per-video citation metrics; pass `channelId` to drill down to a single channel. ## OpenAPI ````yaml https://api.mentionlab.io/api/docs-json post /api/v1/analytics/social/youtube/videos openapi: 3.0.0 info: title: MentionLab Public API v0.3.4-rc description: '' version: 0.3.4-rc contact: {} servers: - url: https://api.mentionlab.io security: [] tags: [] paths: /api/v1/analytics/social/youtube/videos: post: tags: - Analytics - Social summary: List YouTube videos cited in scope description: >- Returns a paginated list of YouTube videos cited by AI responses in the selected scope, with per-video citation metrics; pass `channelId` to drill down to a single channel. operationId: SocialV1Controller_listYoutubeVideos_v1 parameters: - name: x-project-id in: header description: Project ID to specify the project context required: true schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/YoutubeVideosDto' responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/YoutubeVideosResponse' '400': description: >- The request failed validation — the body, query or path parameters are malformed or out of range. content: application/json: schema: $ref: '#/components/schemas/ApiErrorResponse' '401': description: The request is missing valid authentication credentials. content: application/json: schema: $ref: '#/components/schemas/ApiErrorResponse' '403': description: >- The authenticated principal lacks the required permission, or access to the requested organisation/project. content: application/json: schema: $ref: '#/components/schemas/ApiErrorResponse' components: schemas: YoutubeVideosDto: type: object properties: startDate: type: string description: Start date (inclusive) example: '2025-01-01' endDate: type: string description: End date (exclusive) example: '2025-02-01' countries: description: Filter by country codes example: - BE - FR type: array items: type: string languages: description: Filter by language codes example: - en - fr type: array items: type: string models: description: Filter by AI models example: - gpt-4o - claude-3-5-sonnet type: array items: type: string queryIds: description: Filter by query IDs example: - 3fa85f64-5717-4562-b3fc-2c963f66afa6 type: array items: type: string hasSources: type: string description: >- Filter by source presence: "sources" (only with sources), "no_sources" (only without), "all" (no filter). Legacy true/false values are still accepted. enum: - all - sources - no_sources hasShopping: type: string description: >- Filter by shopping presence: "shopping" (only with shopping), "no_shopping" (only without), "all" (no filter). Legacy true/false values are still accepted. enum: - all - shopping - no_shopping queryTagIds: description: Filter by query tag IDs (numeric — bigint column) example: - '42' type: array items: type: string execTagIds: description: Filter by execution tag IDs example: - 3fa85f64-5717-4562-b3fc-2c963f66afa6 type: array items: type: string queryTagGroupIds: description: >- Filter by query tag group IDs — matches rows carrying any tag filed under a selected group. Combines with queryTagIds per queryTagMode. example: - 3fa85f64-5717-4562-b3fc-2c963f66afa6 type: array items: type: string execTagGroupIds: description: >- Filter by execution tag group IDs — matches rows carrying any tag filed under a selected group. Combines with execTagIds per execTagMode. example: - 3fa85f64-5717-4562-b3fc-2c963f66afa6 type: array items: type: string queryTypes: type: array description: >- Filter by query type. Include "untyped" to also match queries without a type. Results from since-deleted queries are excluded when this filter is set. items: type: string enum: - comparative - informative - perception - untyped queryTagMode: type: string description: >- Query tag matching mode: "or" matches ANY tag (default), "and" matches ALL tags. enum: - and - or default: or execTagMode: type: string description: >- Execution tag matching mode: "or" matches ANY tag (default), "and" matches ALL tags. enum: - and - or default: or timezone: type: string description: >- IANA timezone for date bucketing and filtering (e.g. "Europe/Brussels"). Defaults to UTC. example: Europe/Brussels default: UTC groupBy: type: string description: >- Row grouping level for entity results. "none" = one row per entity, "division" = one row per division (entities not in a division get their own row), "group" = one row per top-level group (divisions roll up into their group). Defaults to "none". enum: - none - division - group groupByEntityGroup: type: boolean description: >- Deprecated — use groupBy instead. true is equivalent to groupBy="group". deprecated: true example: false showAllEntities: type: boolean description: >- Include entities that have only ever been seen in a single AI response. These are mostly one-off extraction noise and are hidden by default. example: false page: type: number description: Page number (1-based). default: 1 example: 1 pageSize: type: number description: Items per page (max 200). default: 50 example: 50 channelId: type: string description: >- Drill-down filter: restrict results to videos from a specific YouTube channel. Uses the YouTube-side channel ID, not our internal UUID. example: UCsXVk37bltHxD1rDPwtNM8Q channelCountry: type: string description: >- Drill-down filter: restrict results to videos whose channel's home country (latest snapshot) matches this ISO code. Powers the per-country sheet. Distinct from the `country` scope filter, which is the query/market country. example: US search: type: string description: >- Case-insensitive substring filter on the latest video title. SQL wildcards ('%', '_') and backslashes are escaped and treated literally. example: product review sort: description: >- Ordering directives applied to the result set. Each entry pairs a sortable field with a direction. Allowed fields: title, publishedAt, durationSeconds, isShort, viewCount, likeCount, commentCount, channelName, citationCount, citationShare, citationRate, uniqueQueryCount, firstCitedAt, lastCitedAt. example: - field: viewCount direction: DESC type: array items: $ref: '#/components/schemas/SortOptions' YoutubeVideosResponse: type: object properties: globalYoutubeCitations: type: number description: >- Total distinct AI responses in scope that cited any YouTube video. Denominator for `citationShare`. example: 733 totalResponses: type: number description: >- Total number of AI responses in the filtered scope. Used as the denominator for `citationRate`. example: 2140 results: description: Per-video rows for the current page. type: array items: $ref: '#/components/schemas/YoutubeVideoListItem' page: description: Pagination metadata. allOf: - $ref: '#/components/schemas/Paging' required: - globalYoutubeCitations - totalResponses - results - page ApiErrorResponse: type: object properties: statusCode: type: number description: HTTP status code of the error. example: 400 message: type: string description: >- Human-readable description of the error. Validation failures return an array of per-field validation errors instead of a single string. example: Validation failed error: type: string description: Short name of the HTTP error. example: Bad Request required: - statusCode SortOptions: type: object properties: field: type: string description: Field name to sort by direction: type: string enum: - ASC - DESC description: Sort direction required: - field - direction YoutubeVideoListItem: type: object properties: videoId: type: string description: YouTube-side video ID (11 chars). example: _wbc-UEur4c url: type: string description: Canonical YouTube watch URL, synthesized from `videoId`. example: https://www.youtube.com/watch?v=_wbc-UEur4c title: type: string description: Video title (from latest snapshot). nullable: true example: The Egg - A Short Story thumbnailUrl: type: string description: Video thumbnail URL (medium size, from latest snapshot). nullable: true example: https://i.ytimg.com/vi/_wbc-UEur4c/mqdefault.jpg publishedAt: type: string description: When the video was published on YouTube. nullable: true example: '2019-10-04T14:00:00.000Z' durationSeconds: type: number description: >- Length of the video in seconds, parsed from YouTube's ISO 8601 duration on the latest snapshot. Null when YouTube did not return a duration (e.g. livestream in progress) or the value was unparseable. nullable: true example: 933 isShort: type: boolean description: >- Whether the citing URL is a YouTube Shorts URL (`/shorts/`). Derived from the citation URL at the producer; the YouTube Data API itself does not expose a "short" flag. Reflects the latest snapshot. example: false viewCount: type: string description: View count at time of latest snapshot. nullable: true example: '42385123' likeCount: type: string description: Like count at time of latest snapshot. nullable: true example: '1254321' commentCount: type: string description: Comment count at time of latest snapshot. nullable: true example: '48291' favoriteCount: type: string description: Favorite count at time of latest snapshot. nullable: true example: '0' channelId: type: string description: YouTube-side channel ID that owns this video. example: UCsXVk37bltHxD1rDPwtNM8Q channelName: type: string description: Channel display name (from latest channel snapshot). nullable: true example: Kurzgesagt – In a Nutshell citationCount: type: number description: Distinct AI responses in scope that cited this video (any snapshot). example: 42 citationShare: type: number description: >- This video's share of YouTube-video citations in scope. Formula: (citationCount / total AI responses citing any YT video in scope) × 100. Null when no YouTube citations exist in scope (denominator = 0). nullable: true example: 5.73 citationRate: type: number description: >- Citation rate — how often this video appears across ALL AI responses in scope. Formula: (citationCount / totalResponses) × 100. Null when no AI responses exist in scope (denominator = 0). nullable: true example: 1.96 uniqueQueryCount: type: number description: Distinct queries in scope whose AI responses cited this video. example: 7 firstCitedAt: type: string description: >- Earliest citation timestamp (initiated_at of the oldest AI response that cited this video, within filter scope). example: '2026-04-01T09:12:34.000Z' lastCitedAt: type: string description: Latest citation timestamp within filter scope. example: '2026-04-24T18:45:12.000Z' lastSnapshotId: type: string description: Identifier of the most recent metadata snapshot for this video. example: 01924f6a-7b90-7c11-9b8a-123456789abc required: - videoId - url - title - thumbnailUrl - publishedAt - durationSeconds - isShort - viewCount - likeCount - commentCount - favoriteCount - channelId - channelName - citationCount - citationShare - citationRate - uniqueQueryCount - firstCitedAt - lastCitedAt - lastSnapshotId Paging: type: object properties: totalRecords: type: number limit: type: number currentPage: type: number totalPages: type: number nextPage: type: number prevPage: type: number required: - totalRecords - limit - currentPage - totalPages - nextPage - prevPage ````