> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tryprofound.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Videos
> Rank cited YouTube videos, for one channel or across all of them.
Rank cited YouTube videos, for one channel or across all of them. Calculated
from Profound's citation data, not YouTube analytics.
* **Source types:** `video`, `short`, `channel`, `playlist`, or `other`.
`other` is available with `unattributed` or `all`; with the default
`attributed` mode, requests containing `other` are rejected. Omit
`source_types` to return `video` and `short` with the default `attributed`
mode; `unattributed` and `all` widen the default to all five source types.
Provide a non-empty list; duplicate values are de-duplicated.
* **Attribution:** `attributed` (the default), `unattributed`, or `all`.
An unattributed row has no channel: `source_type` is `other` for a search or
feed URL that names no source, and any other type is a source we have no
channel for.
* **Grouping and time series:** Not supported. `/videos` accepts no `group_by`
or `interval`; unknown fields are rejected.
* **Pagination:** `limit` defaults to 10 and accepts 1–50. Pass the opaque
`info.next_cursor` back as the request `cursor` to get the next page;
`info` echoes your `cursor` on pages after the first. The response `info`
echoes `category_id`, the effective `limit`, and `attribution`.
* **Filters:** Prompt-level fields are `model`, `topic`, `region`, `prompt`,
`persona`, `tag`, and `analysis_type`. The `channel` filter accepts `is`,
`in`, `contains`, `not_contains`, `contains_case_insensitive`, and
`not_contains_case_insensitive`: `is`/`in` select exact handles, while the
other operators match channel titles or handles.
`domain` and `page` are rejected. A `channel` leaf cannot share an `or` or
`not` with a prompt-level leaf; put separate layers in `and` clauses.
The v2 reports share a request shape and filter tree. See
[Filtering & concepts](/rest-api/reports/reports-v2-overview) for filter
operators, date ranges, pagination, and filter depth. Grouping and time
series guidance does not apply to this endpoint.
```bash cURL theme={null}
curl -X POST https://api.tryprofound.com/v2/reports/social/youtube/videos \
-H "X-API-Key: " \
-H "Content-Type: application/json" \
-d '{
"category_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
"start_date": "2026-06-01",
"end_date": "2026-06-30",
"filter": {
"field": "channel",
"op": "in",
"value": ["examplechannel"]
},
"attribution": "attributed",
"limit": 10
}'
```
```json 200 theme={null}
{
"info": {
"category_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
"total_results": 1,
"count": 1,
"next_cursor": null,
"limit": 10,
"attribution": "attributed",
"models": ["ChatGPT", "Google Gemini"],
"start_date": "2026-06-01",
"end_date": "2026-06-30",
"filter": {
"field": "channel",
"op": "in",
"value": ["examplechannel"]
},
"source_types": ["video", "short"]
},
"data": [
{
"video_id": "dQw4w9WgXcQ",
"source_type": "video",
"title": "Example Video",
"channel_title": "Example Channel",
"channel_handle": "examplechannel",
"url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
"channel_url": "https://www.youtube.com/@examplechannel",
"rank": 1,
"published_at": "2026-06-12",
"duration_seconds": 245,
"video_category": "Education",
"count": 73,
"citation_share": 0.21
}
]
}
```
## OpenAPI
````yaml POST /v2/reports/social/youtube/videos
openapi: 3.1.0
info:
title: External API
version: 86af1652d4f82e2143ff2f8a2c82349f124e7999
servers:
- url: https://api.tryprofound.com
description: Production Server
security: []
paths:
/v2/reports/social/youtube/videos:
post:
tags:
- Reports
- Reports
summary: Query Youtube Videos
description: Rank cited YouTube videos, for one channel or across all of them.
operationId: query_youtube_videos_v2_reports_social_youtube_videos_post
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/YoutubeVideosQuery'
required: true
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/YoutubeVideosResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- APIKeyHeader: []
- BearerAuth: []
x-codeSamples:
- lang: JavaScript
source: |-
import Profound from '@profoundai/client';
const client = new Profound({
apiKey: process.env['PROFOUND_API_KEY'], // This is the default and can be omitted
});
const response = await client.reports.social.youtube.getVideos({
category_id: '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
end_date: 'end_date',
start_date: 'start_date',
});
console.log(response.data);
- lang: Python
source: |-
import os
from profound import Profound
client = Profound(
api_key=os.environ.get("PROFOUND_API_KEY"), # This is the default and can be omitted
)
response = client.reports.social.youtube.get_videos(
category_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
end_date="end_date",
start_date="start_date",
)
print(response.data)
components:
schemas:
YoutubeVideosQuery:
properties:
category_id:
type: string
format: uuid
title: Category Id
start_date:
type: string
title: Start Date
description: YYYY-MM-DD, ET, inclusive
end_date:
type: string
title: End Date
description: YYYY-MM-DD, ET, inclusive
filter:
anyOf:
- $ref: '#/components/schemas/FilterNode'
- type: 'null'
description: >-
Advanced filter tree. Prompt-level dimensions are `model`, `topic`,
`region`, `prompt`, `persona`, `tag`, `analysis_type`. `channel`
covers both channel cases: `in` with a list of handles selects
exactly those channels, resolving each handle to its channel so a
renamed channel is never returned in pieces; `contains` matches a
channel's title or handle by name. Combine with `and`/`or`/`not` up
to 3 deep. An exact `channel` selection must be its own `and`
clause, and a `channel` leaf cannot share an `or` or `not` with a
prompt-level leaf, because those compile at different stages of the
query. `domain` and `page` are rejected rather than approximated:
every row here is one domain, and `page` is not a video id.
limit:
anyOf:
- type: integer
maximum: 50
exclusiveMinimum: 0
- type: 'null'
title: Limit
description: Page size; default 10, max 50.
cursor:
anyOf:
- type: string
- type: 'null'
title: Cursor
source_types:
anyOf:
- items:
type: string
enum:
- video
- short
- channel
- playlist
- other
type: array
- type: 'null'
title: Source Types
description: >-
Limit results to YouTube source types: `video`, `short`, `channel`,
`playlist`, or `other`. Omit to include `video` and `short` with the
default `attribution='attributed'`; `unattributed` and `all` widen
the default to all five source types. Requests containing `other`
with `attribution='attributed'` are rejected.
attribution:
type: string
enum:
- attributed
- unattributed
- all
title: Attribution
description: >-
Choose attributed citations, unattributed citations, or all
citations. An unattributed row has no channel: `source_type` is
`other` for a search or feed URL that names no source, and any other
type is a source we have no channel for.
default: attributed
additionalProperties: false
type: object
required:
- category_id
- start_date
- end_date
title: YoutubeVideosQuery
description: Cited videos, optionally narrowed to specific channels.
YoutubeVideosResponse:
properties:
info:
$ref: '#/components/schemas/YoutubeVideosInfo'
data:
items:
$ref: '#/components/schemas/YoutubeVideoRow'
type: array
title: Data
type: object
required:
- info
- data
title: YoutubeVideosResponse
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
FilterNode:
properties:
and:
anyOf:
- items:
$ref: '#/components/schemas/FilterNode'
type: array
- type: 'null'
title: And
or:
anyOf:
- items:
$ref: '#/components/schemas/FilterNode'
type: array
- type: 'null'
title: Or
not:
anyOf:
- $ref: '#/components/schemas/FilterNode'
- type: 'null'
field:
anyOf:
- type: string
- type: 'null'
title: Field
op:
anyOf:
- type: string
- type: 'null'
title: Op
value:
title: Value
additionalProperties: false
type: object
title: FilterNode
description: A leaf (`field`/`op`/`value`) or an `and`/`or`/`not` group.
YoutubeVideosInfo:
properties:
total_results:
anyOf:
- type: integer
- type: 'null'
title: Total Results
description: >-
Total rows matching the query before pagination (null when not
computed).
count:
type: integer
title: Count
description: Number of rows returned in `data` for this page.
next_cursor:
anyOf:
- type: string
- type: 'null'
title: Next Cursor
description: Opaque cursor for the next page; null on the last page.
models:
items:
type: string
type: array
title: Models
description: Display names of the models the report covers.
start_date:
type: string
title: Start Date
description: Echoed request start date (YYYY-MM-DD, ET).
end_date:
type: string
title: End Date
description: Echoed request end date (YYYY-MM-DD, ET).
filter:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Filter
description: Echoed normalized filter tree, or null when no filter was sent.
category_id:
type: string
format: uuid
title: Category Id
description: Echoed category id this report covers.
source_types:
items:
type: string
enum:
- video
- short
- channel
- playlist
- other
type: array
title: Source Types
description: >-
Source types this report covers. Derived from the request, not
returned rows, so a listed type may have no rows.
cursor:
anyOf:
- type: string
- type: 'null'
title: Cursor
description: Echoed request cursor; omitted on the first page.
limit:
type: integer
title: Limit
description: Effective page size applied to this paged report.
attribution:
type: string
enum:
- attributed
- unattributed
- all
title: Attribution
description: Effective video attribution mode.
additionalProperties: true
type: object
required:
- count
- models
- start_date
- end_date
- category_id
- source_types
- limit
- attribution
title: YoutubeVideosInfo
description: >-
Video report metadata, including effective paging and attribution
settings.
YoutubeVideoRow:
properties:
video_id:
type: string
title: Video Id
description: YouTube video id, as in the watch URL.
source_type:
type: string
enum:
- video
- short
- channel
- playlist
- other
title: Source Type
description: >-
YouTube source type: `video`, `short`, `channel`, `playlist` or
`other`.
title:
anyOf:
- type: string
- type: 'null'
title: Title
description: Resolved title, or null when unavailable.
channel_title:
anyOf:
- type: string
- type: 'null'
title: Channel Title
description: Publishing channel title, or null when unknown.
channel_handle:
anyOf:
- type: string
- type: 'null'
title: Channel Handle
description: >-
Handle of the publishing channel; select it with a `channel` filter
of `in`. Null when unknown.
url:
anyOf:
- type: string
- type: 'null'
title: Url
description: Openable video URL, or null when unavailable.
channel_url:
anyOf:
- type: string
- type: 'null'
title: Channel Url
description: Openable URL for the publishing channel, or null when unknown.
rank:
type: integer
title: Rank
description: 1-based position in the full ranked set, continuing across pages.
published_at:
anyOf:
- type: string
- type: 'null'
title: Published At
description: Upload date, or null when unknown.
duration_seconds:
anyOf:
- type: integer
- type: 'null'
title: Duration Seconds
description: Length in seconds, or null when unknown.
video_category:
anyOf:
- type: string
- type: 'null'
title: Video Category
description: YouTube content category, or null when unknown.
count:
type: integer
title: Count
description: Citations attributed to this video.
citation_share:
type: number
title: Citation Share
description: >-
Share of every YouTube citation in the window (attributed and
unattributed alike), regardless of `source_types`. Shares sum to at
most 1, reaching about 1 only with `attribution="all"` and no
`source_types` filter; a narrowed ranking sums to its slice's share.
additionalProperties: true
type: object
required:
- video_id
- source_type
- rank
- count
- citation_share
title: YoutubeVideoRow
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
msg:
type: string
title: Message
type:
type: string
title: Error Type
input:
title: Input
ctx:
type: object
title: Context
type: object
required:
- loc
- msg
- type
title: ValidationError
securitySchemes:
APIKeyHeader:
type: apiKey
in: header
name: X-API-Key
BearerAuth:
type: http
scheme: bearer
````