Skip to main content
POST
Rank the YouTube channels cited in a category, or the video categories they publish in. Calculated from Profound’s citation data, not YouTube analytics.
  • Source types: video, short, channel, playlist, or other. Omit source_types to include video, short, channel, and playlist. Provide a non-empty list; duplicate values are de-duplicated. Rollups cannot include other, because those citations have no channel.
  • group_by: channel (the default), video_category, or source_type. Supported cross-tabs are ["channel", "video_category"], ["channel", "source_type"], and ["channel", "model"]. Duplicate dimensions are rejected.
  • Time series: Set interval to day, week, or month to return one row per entity per period. date is the bucket start in ET, so a weekly or monthly bucket can start before start_date. Omit it for window totals.
  • Rows: Fields are conditional: date, model, source_type, and video_category appear only with the matching interval or group_by. With group_by: ["video_category"], the category is returned in name, not video_category. An unresolved video category is returned as "", not null. rank is the leading channel’s rank in the full ranked set and is repeated across that channel’s cross-tab rows.
  • 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 interval.
  • Totals: total_results counts distinct channels in the window, while count is the number of rows returned; they use different units.
  • 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.
For cross-tabs, limit counts leading channels, not returned rows. For example, limit: 25 with group_by: ["channel", "video_category"] returns 25 channels but can return more than 25 rows.
The v2 reports share a request shape and filter tree. See Filtering & concepts for filter operators, grouping, date ranges, pagination, and filter depth.

Authorizations

​
X-API-Key
string
header
required

Body

application/json

Channel and category rollups.

​
category_id
string<uuid>
required
​
start_date
string
required

YYYY-MM-DD, ET, inclusive

​
end_date
string
required

YYYY-MM-DD, ET, inclusive

​
filter
FilterNode · object | null

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
integer | null

Page size; default 10, max 50.

Required range: 0 < x <= 50
​
cursor
string | null
​
source_types
enum<string>[] | null

Limit results to YouTube source types: video, short, channel, playlist, or other. Omit to include video, short, channel, and playlist; other is excluded because those citations have no channel. Requests containing other are rejected.

Available options:
video,
short,
channel,
playlist,
other
​
group_by
enum<string>[]

What each row represents. Empty or ["channel"] ranks channels; ["video_category"] ranks content categories; ["source_type"] ranks source types; ["channel", "video_category"], ["channel", "source_type"] and ["channel", "model"] return cross-tabs — a row per channel per category, or per answer engine. limit counts leading channels in every case, so ten channels across nine engines is ten channels and ninety rows.

Available options:
channel,
video_category,
model,
source_type
​
interval
enum<string> | null

Return a time series instead of window totals: one row per entity per period, each carrying date. citation_share is then relative to that period, so the series is comparable across periods. Omit for window totals.

Available options:
day,
week,
month

Response

Successful Response

​
info
YoutubeChannelsInfo · object
required

Channel report metadata, including effective paging and grouping settings.

​
data
YoutubeChannelRow · object[]
required