> ## 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.
# 動画
> Rank cited YouTube videos, for one channel or across all of them.
引用された YouTube 動画を、1 つのチャンネルについて、またはすべてのチャンネルを対象にランク付けします。
YouTube のアナリティクスではなく、Profound の引用データから算出されます。
* **ソースタイプ:** `video`、`short`、`channel`、`playlist`、または `other`。
`other` は `unattributed` または `all` で使用できます。デフォルトの
`attributed` モードでは、`other` を含むリクエストは拒否されます。デフォルトの `attributed`
モードで `source_types` を省略すると `video` と `short` が返されます。
`unattributed` と `all` では、デフォルトが 5 つすべてのソースタイプに広がります。
空でないリストを指定してください。重複する値は排除されます。
* **帰属:** `attributed` (デフォルト)、`unattributed`、または `all`。
未帰属の行にはチャンネルがありません。ソースを示さない検索やフィードの URL では
`source_type` が `other` になり、それ以外のタイプはチャンネルを特定できないソースです。
* **グループ化と時系列:** サポートされていません。`/videos` は `group_by`
や `interval` を受け付けず、不明なフィールドは拒否されます。
* **ページネーション:** `limit` のデフォルトは 10 で、1–50 を指定できます。不透明な
`info.next_cursor` をリクエストの `cursor` として渡すと次のページを取得できます。
2 ページ目以降では、`info` に指定した `cursor` がエコーされます。レスポンスの `info`
には、`category_id`、実際に適用された `limit`、`attribution` がエコーされます。
* **フィルタ:** プロンプトレベルのフィールドは `model`、`topic`、`region`、`prompt`、
`persona`、`tag`、`analysis_type` です。`channel` フィルタは `is`、
`in`、`contains`、`not_contains`、`contains_case_insensitive`、
`not_contains_case_insensitive` を受け付けます。`is`/`in` は完全一致のハンドルを選択し、
その他の演算子はチャンネルのタイトルまたはハンドルに一致します。
`domain` と `page` は拒否されます。`channel` のリーフは、プロンプトレベルのリーフと同じ `or` や
`not` に含めることはできません。異なるレイヤーは `and` 句に分けてください。
v2 レポートは共通のリクエスト形式とフィルタツリーを使用します。フィルタ
演算子、期間、ページネーション、フィルタの深さについては、
[フィルタリングと概念](/ja-jp/rest-api/reports/reports-v2-overview) を参照してください。グループ化と時系列
に関するガイダンスは、このエンドポイントには適用されません。
```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: 0.60.2
x-scalar-sdk-installation:
- lang: Python
description: |-
```sh
pip install profound
```
- lang: TypeScript
description: |-
```sh
npm install @profoundai/client
```
- lang: Rust
description: |-
```sh
cargo add profound
```
servers:
- url: https://api.tryprofound.com
description: Production Server
security:
- APIKeyHeader:
- X-API-Key
- BearerAuth: []
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:
- label: Python
lang: Python
source: |-
import os
from profound import Profound
client = Profound(
api_key=os.environ.get("PROFOUND_API_KEY"),
)
youtube = client.reports.social.youtube.get_videos(
category_id="7c9e6679-7425-40de-944b-e07fc1f90ae7",
start_date="",
end_date="",
attribution="attributed",
)
print(youtube)
- label: TypeScript
lang: TypeScript
source: |-
import Profound from '@profoundai/client';
const client = new Profound({
apiKey: process.env['PROFOUND_API_KEY'], // defaults to the PROFOUND_API_KEY env var
environment: 'production',
});
const youtube = await client.reports.social.youtube.getVideos({
category_id: '7c9e6679-7425-40de-944b-e07fc1f90ae7',
start_date: '',
end_date: '',
attribution: 'attributed',
});
console.log(youtube);
- label: rust
lang: rust
source: |-
use profound::*;
#[tokio::main]
async fn main() -> Result<(), Box> {
let client = ProfoundClient::builder()
.api_key(std::env::var("PROFOUND_API_KEY")?)
.build()?;
let response = client
.reports()
.social()
.youtube()
.get_videos(YoutubeVideosQuery {
category_id: "7c9e6679-7425-40de-944b-e07fc1f90ae7".to_string(),
start_date: "".to_string(),
end_date: "".to_string(),
filter: None,
limit: None,
cursor: None,
source_types: None,
attribution: None,
})
.send()
.await?;
println!("{:?}", response);
Ok(())
}
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
bearerFormat: JWT
````