> ## Documentation Index > Fetch the complete documentation index at: https://docs.athenahq.ai/llms.txt > Use this file to discover all available pages before exploring further. # List YouTube Videos > List YouTube videos cited in AI answers for a website, ordered by citation count. Returns saved titles, channel details, categories, durations, publication dates, citation counts, distinct-response citation percentages and linked timestamps. Watch, Shorts and short-link variants of one video are combined. Filter by channel_key or video_id. Metadata may be pending or missing; no live YouTube fetch is performed. Dates are inclusive UTC days. Counts cover citations in Athena-tracked AI answers, not YouTube views or subscriber analytics. Metadata is read from Athena’s saved cache and may be unavailable. Channel share uses all YouTube citations, including non-video links; category and length shares use video citations. Video citation_percentage is the percentage of distinct filtered AI responses citing that video. first_seen is within the selected date range. The completed breakdown, including citation metrics and saved metadata, is cached for up to five minutes. The moments array contains seconds from the top 100 cited URL variants per video; it is not an exhaustive timestamp list or a transcript. channel_key and video_id narrow returned videos without changing the response denominator. ## OpenAPI ````yaml /api-reference/openapi.json post /api/v1/sources/youtube-videos openapi: 3.1.0 info: title: AthenaHQ API description: >- AthenaHQ API provides programmatic access to manage your websites and prompts for AI-powered content optimization. version: 1.0.0 contact: email: support@athenahq.ai servers: - url: https://api.athenahq.ai description: Production server security: - apiKey: [] tags: - name: Basics description: Core API operations for managing websites and prompts - name: Metrics description: Metrics and analytics endpoints for tracking AI visibility - name: Billing description: Billing and credits endpoints for managing usage - name: Team Management description: Endpoints for managing team members and invitations - name: Groups description: Endpoints for managing groups of websites - name: Content description: >- Endpoints for accessing Content Hub data — tabs, tracked URLs, and per-URL prompt breakdowns. - name: Pitch Workspace description: >- Endpoints for accessing pitch workspace reports — org-scoped pitch runs with competitors, prompts, attributes, and aggregate metrics. - name: Knowledge Base description: >- Endpoints for reading the brand Knowledge Base — approved brand facts and the pillars that organize them. paths: /api/v1/sources/youtube-videos: post: tags: - Sources summary: List YouTube Videos description: >- List YouTube videos cited in AI answers for a website, ordered by citation count. Returns saved titles, channel details, categories, durations, publication dates, citation counts, distinct-response citation percentages and linked timestamps. Watch, Shorts and short-link variants of one video are combined. Filter by channel_key or video_id. Metadata may be pending or missing; no live YouTube fetch is performed. Dates are inclusive UTC days. Counts cover citations in Athena-tracked AI answers, not YouTube views or subscriber analytics. Metadata is read from Athena’s saved cache and may be unavailable. Channel share uses all YouTube citations, including non-video links; category and length shares use video citations. Video citation_percentage is the percentage of distinct filtered AI responses citing that video. first_seen is within the selected date range. The completed breakdown, including citation metrics and saved metadata, is cached for up to five minutes. The moments array contains seconds from the top 100 cited URL variants per video; it is not an exhaustive timestamp list or a transcript. channel_key and video_id narrow returned videos without changing the response denominator. operationId: sources.youtubeVideos requestBody: required: true content: application/json: schema: type: object properties: website_id: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ filters: type: object properties: start_date: type: string format: date pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$ description: First day, YYYY-MM-DD, inclusive (UTC). schedule_id: description: >- One schedule: "default" or a custom/archived schedule UUID. Omit for Default, which includes all pre-cutover history and ad hoc runs. The retired "manual" token is accepted as an alias of "default". Schedules cannot be combined. anyOf: - type: string enum: - default - manual - type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ end_date: description: >- Last day, YYYY-MM-DD, inclusive (UTC). Defaults to today. type: string format: date pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$ models: description: >- AI models to include, as an array even for one model — e.g. ["chatgpt", "perplexity"]. Omit to include all models. type: array items: type: string enum: - chatgpt - perplexity - gemini - google_ai_overview - copilot - claude - ai_mode - grok - deepseek - meta_ai - mistral prompt_ids: description: >- Prompt UUIDs to filter to, as an array even for one id. Omit for all prompts. type: array items: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ location_ids: description: >- Location UUIDs to filter to, as an array even for one id. The literal string "no-location" selects responses that ran without a location. Omit for all locations. type: array items: anyOf: - type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ - type: string const: no-location persona_ids: description: >- Persona UUIDs to filter to, as an array even for one id. Omit for all personas. type: array items: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ target_identifiers: description: >- Target identifier strings to filter to, as an array even for one value. The literal string "no-identifier" selects responses with no target identifier. Omit for all. type: array items: anyOf: - type: string - type: string const: no-identifier variation_filter: description: >- Which prompt rows to include, as an array: "prompt" for base prompts, "variation" for generated variations, or both. Omit for both. type: array items: type: string enum: - variation - prompt prompt_tags: description: Prompt tag UUIDs from get_prompt_tags. type: array items: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ prompt_tags_operator: description: >- How prompt_tags combine: "is_any_of" matches prompts with any listed tag, "has_all_of" only prompts carrying every listed tag. type: string enum: - is_any_of - has_all_of prompt_status: description: >- Filter prompts by tracking status: "active" or "paused". Omit for both. type: string enum: - active - paused prompt_type: description: >- Filter prompts by type: "branded" (mentions the brand) or "non_branded". Omit for both. type: string enum: - branded - non_branded required: - start_date additionalProperties: false page_num: default: 0 description: Zero-based page number. type: integer minimum: 0 maximum: 1000000 page_size: type: integer minimum: 1 maximum: 100 default: 30 channel_key: description: >- Channel group key from get_youtube_creators; omit for all creators. type: string minLength: 1 maxLength: 500 video_id: description: YouTube video ID; omit for all videos. type: string pattern: ^[A-Za-z0-9_-]{11}$ required: - website_id - filters example: website_id: 123e4567-e89b-42d3-a456-426614174000 filters: start_date: '2026-10-01' end_date: '2026-10-31' page_num: 0 page_size: 30 responses: '200': description: Success content: application/json: schema: type: object properties: videos: type: array items: type: object properties: video_id: type: string url: type: string title: type: - string - 'null' channel: type: object properties: channel_key: type: string description: >- Stable group key; use as channel_key in get_youtube_videos. channel_id: type: - string - 'null' name: type: - string - 'null' handle: type: - string - 'null' url: type: - string - 'null' thumbnail_url: type: - string - 'null' required: - channel_key - channel_id - name - handle - url - thumbnail_url additionalProperties: false category_id: anyOf: - type: integer minimum: -9007199254740991 maximum: 9007199254740991 - type: 'null' duration_seconds: anyOf: - type: integer minimum: -9007199254740991 maximum: 9007199254740991 - type: 'null' published_at: type: - string - 'null' first_seen: type: string citations: type: number citation_percentage: type: number details_status: type: string enum: - found - pending - missing moments: type: array items: type: integer minimum: 0 maximum: 9007199254740991 description: >- Distinct linked timestamps in seconds, from the top 100 cited URL variants. This is a bounded list, not every timestamp or transcript. required: - video_id - url - title - channel - category_id - duration_seconds - published_at - first_seen - citations - citation_percentage - details_status - moments additionalProperties: false pagination: type: object properties: page_num: type: integer minimum: -9007199254740991 maximum: 9007199254740991 page_size: type: integer minimum: -9007199254740991 maximum: 9007199254740991 total: type: integer minimum: -9007199254740991 maximum: 9007199254740991 required: - page_num - page_size - total additionalProperties: false notice: type: string required: - videos - pagination additionalProperties: false '400': description: Bad Request — validation failed content: application/json: schema: type: object properties: error: type: string required: - error '401': description: Unauthenticated content: application/json: schema: type: object properties: error: type: string required: - error '403': description: Forbidden content: application/json: schema: type: object properties: error: type: string required: - error '404': description: Not Found content: application/json: schema: type: object properties: error: type: string required: - error '409': description: Conflict content: application/json: schema: type: object properties: error: type: string required: - error '429': description: Rate Limited content: application/json: schema: type: object properties: error: type: string required: - error '500': description: Internal Error content: application/json: schema: type: object properties: error: type: string required: - error security: - apiKey: [] components: securitySchemes: apiKey: type: apiKey in: header name: x-api-key description: >- API key for authentication. You can create one [here](https://app.athenahq.ai/organization?tab=api). ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.