media_collections_get

Read playlists, OTT/serial series, course collections, available posts or source-reported course student progress and period statistics pages for one installed app.

Inputs and views

channelCode and pAppCode are required. Supported apps: C00001, C00002, C00006, C00007.

For list/posts, query accepts page 1–10000 (default 1), limit 15/30/50/100 (default 15), optional search up to 200 characters and optional isPublished. Read each required page; one list page is not the full inventory.

Results and identifiers

List results use MEDIA_COLLECTIONS or MEDIA_POST_CHOICES with items and pagination. The creationRevision binds the current channel/app context, not the full collection inventory. Detail returns MEDIA_COLLECTION, series, ordered episodes, optional course curriculum/preview state and revision. Invalid identities, pagination, disconnected episode order or inconsistent curriculum fail closed.

Use media_collection_apply with list creationRevision for creation, the labels-view revision for label assignments and detail revision for other existing-collection actions. Select source post IDs when adding connections, episode IDs when moving/disconnecting flat connections, and curriculum item/chapter IDs for course structure. These IDs are not interchangeable. Existing course VOD, text and coaching sessions may be read; this does not grant permission to create coaching or verify video playback.

Read the media workflow guide for authorization, source-versus-runtime availability and common recovery rules.

Input example

Illustrative input only. Replace the channel, installed app, identifiers and revision with values obtained for the selected target.

{
  "channelCode": "selected-channel",
  "pAppCode": "C00002",
  "view": {
    "kind": "detail",
    "seriesId": 1
  }
}

OTT and course collection labels

Basic VOD and serial collections do not support this control. No caller label type, filter or pagination is accepted by this view.

MEDIA_COLLECTION_LABELS returns the verified series with series.labels, ordered episodes, course curriculum/preview state when applicable, labelCatalog, revision and writesPerformed:false. Linked labels and catalog entries expose only id, name and type, sorted by ID. The revision binds these stable catalog values and the entire parsed collection snapshot. Use it with action.kind:labels; an ordinary detail revision cannot authorize assignment. Catalog creation/rename/deletion/order use the separate media label writer, not this assignment workflow.

The existing API transport reads /seller/api/v1/labels with sortBy:order and order:ASC, scoped to the exact installed consumer. It inspects at most1,000 catalog entries, a bridge bound. Source pagination may be absent; when supplied it must describe one complete first page whose total equals the returned count and whose limit covers it. Incomplete catalogs, duplicate IDs, wrong categories, missing/malformed linked arrays or linked id/name/type values differing from the catalog are refused. Errors never become empty choices. Labels have no response consumer echo: scope relies on authenticated exact-consumer transport, not independent server ownership proof.

Global usage counts and catalog sort positions are not assignment state and may change. They are validated by the catalog reader but omitted from this stable projection; do not infer display order, count preservation, global completeness beyond the accepted response contract or visitor filtering. Unknown fields outside the existing parsed series schema are outside preservation.

The existing exact collection destination remains C00002 series/:seriesId or C00007 classes/:seriesId.

Illustrative labels read for an observed OTT series, not a recorded call:

{"channelCode":"selected-channel","pAppCode":"C00002","view":{"kind":"labels","seriesId":7}}

Course student summary pages

No seriesId, student ID, revision or requestId is accepted. Other collection apps return MEDIA_COURSE_STUDENTS_UNSUPPORTED. This is an option on the existing getter, with no new tool or task type.

These bounds are bridge limits, not a claim about the UI dropdown or backend limits. The mounted screen submits general search; nickname, profileDistinctId, recentClassTitle, searchword, sort/order and isPublished are not accepted query fields. Read pages separately as needed; no all-pages option or atomic snapshot is provided.

A validated result returns MEDIA_COURSE_STUDENTS, students in source order, pagination:{page,limit,total}, totalPages (at least 1), selected channel/app/installation, writesPerformed:false and learnerActivityVerified:false. The requested page/limit, expected row count, total and unique numeric/profile IDs must agree. A genuine empty or out-of-range page retains its reported total; inconsistent data returns MEDIA_COURSE_STUDENTS_UNVERIFIED instead of an invented empty success.

All projected strings reject control characters. Profile image URLs and unrelated response metadata are omitted. Raw identifiers remain in the output even though a separate display code is masked. Response rows have no consumer echo: selected-context checks do not independently prove profile ownership or per-row consumer ownership.

The optional readCourseStudents hook must use an explicitly configured ANALYTICS connection for the source student-list read. A missing or non-function hook returns MEDIA_COURSE_STUDENTS_HOST_UNAVAILABLE before any analytics or collection-data request. There is no fallback to the ordinary API/LIVE origin. Upstream failures and context/credential/installation changes return no successful student list.

The source screen is C00007 statistics/student-progress. MCP resolves exactly that destination for a fresh successful matching projection, including valid rows, masked display codes, pagination and false write/activity flags, without edit revisions or tasks. Use the returned configured-origin link, never a classes-list fallback or a URL built from student IDs. Shared direct/compact checks use real HttpPublPort with intercepted HTTP; they do not prove actual analytics or console behavior.

This read issues no revision, creationRevision or task ID and changes no learner activity. It cannot establish viewing, attendance, completion or current enrollment beyond the source-reported page. The later student class/session views supersede the domain-level progress backlog; their host connection remains separate. The period statistics views add the bounded aggregate page contract;

Illustrative default first-page input, not a recorded read:

{"channelCode":"selected-channel","pAppCode":"C00007","view":{"kind":"students"}}

Illustrative search and numeric page size. Replace the channel and search with the intended authorized target:

{"channelCode":"selected-channel","pAppCode":"C00007","view":{"kind":"students","query":{"page":2,"limit":20,"search":"Course participant"}}}

Course student class and session progress

Select profileDistinctId from a students row, then seriesId from a student-classes row for student-sessions. Student/class/session row id, course seriesId and session postId are distinct; the masked display code or nickname is not a profile selector.

Both views accept optional query with page 1–10000 (default 1) and any integer limit 1–100 (default 15). They accept no search, title, sort, order or all-pages option. One call reads one requested page without automatically traversing the roster, courses, posts or other pages. seriesId is required only for student-sessions and must be a positive safe integer, not a numeric string.

profileDistinctId is the unchanged source string: nonblank, at most 256 UTF-16 code units, with no controls, slash, backslash, question mark, hash, percent, invalid UTF-16 or exact dot/double-dot segment. Safe Unicode, spaces and colons are retained. The bridge encodes it once as one URI segment; supply the raw ID, not an encoded URL or path. These are bridge guards, not a claim about backend ID syntax.

IDs must be positive safe integers, counts nonnegative safe integers and progressRate a finite nonnegative number. Preserve the supplied rate even above 100 and completed count even above session count: do not recompute a ratio, clamp values or infer actual study. Session type is PLAIN, VOD or LIVE_COACHING and isCompleted is an explicit boolean. Preserve row order and raw times; recentStudiedAt can be null or an empty string. Titles/times have bridge bounds of 2000/128 UTF-16 code units and reject controls. Images and unknown fields are omitted; no media is fetched or played.

Results include normalized pagination:{page,limit,total}, totalPages of at least 1, the selected channel/app/installation and requested profileDistinctId. Returned page/limit, exact row count implied by total and unique row IDs within that page must agree. Duplicate secondary seriesId/postId values in distinct rows are retained. A class array cannot be null. A null session array becomes [] with sourceReportedNull:true only when the requested page is expected to be empty, including an out-of-range page with a nonzero total. Otherwise the result is MEDIA_COURSE_PROGRESS_UNVERIFIED. A returned session array has sourceReportedNull:false. No all-page total or snapshot is synthesized.

targetBinding:scoped-request means the profile and course are request selectors under the authenticated installed-consumer context; the backend does not echo profile/consumer ownership. It is not independent ownership verification. Results report writesPerformed:false and learnerActivityVerified:false, with no revision, creationRevision or durable task. Source counts and completion flags do not verify attendance, viewing, effective enrollment or learning outcomes.

The separate optional readCourseStudentProgress host hook requires the configured ANALYTICS connection. Its exported request builder fixes GET to /seller/api/v1/class-analytics/students/:profileDistinctId/classes, or that path plus /:seriesId/sessions, with string page/limit. It uses the existing selected channel bearer and exact installed-consumer header, with context checks around the request. There is no API/LIVE fallback, ordinary collection request or credential supplied in tool input. Missing/non-function hook returns MEDIA_COURSE_PROGRESS_HOST_UNAVAILABLE; other collection apps return MEDIA_COURSE_PROGRESS_UNSUPPORTED. Upstream errors or changed context do not become empty histories.

Both domain destinations identify C00007/statistics/student-progress/:encodedProfileDistinctId/class without query or fragment. The session panel has no separate route: open that parent student page and select the course there. Session results carry consoleDestination:parent for this reason. Sessions additionally require the selected positive seriesId, valid sourceReportedNull and parent metadata. Extra row fields, historical/error results, revisions/tasks or inconsistent projections receive no fallback link. The workflow guide keeps this connection work explicit.

Illustrative inputs only; replace the selectors with returned IDs.

{"channelCode":"selected-channel","pAppCode":"C00007","view":{"kind":"student-classes","profileDistinctId":"returned-profile-id"}}

{"channelCode":"selected-channel","pAppCode":"C00007","view":{"kind":"student-sessions","profileDistinctId":"returned-profile-id","seriesId":107,"query":{"page":2,"limit":20}}}

Neither set measures actual ANALYTICS traffic. This adds neither a tool nor a task type. Period statistics below use a separate optional hook, with its own connection and verification boundary.

Course and session period statistics

These aggregate pages are distinct from the student roster and per-student progress views above. Neither view accepts a profile ID, seriesId, postId or another app as a substitute.

Period and page inputs

Supply both query.start and query.end as real YYYY-MM-DD dates, or omit both. Dates must be on or after 2022-01-01, start must not follow end, the difference must be less than 93 days, and end must not be later than the current UTC date. Supplying only one date, impossible dates or future end dates is rejected. Explicit date labels are forwarded unchanged.

With no pair, the bridge resolves the period once to the current UTC date minus 31 days through the current UTC date and returns periodSelection:source-default. This is a 31-day difference, or 32 date labels when both endpoints are counted; it does not prove which days the backend includes. Explicit dates return periodSelection:explicit.

query.page is an integer 1–10000, default 1. query.limit is exactly 15, 30, 50 or 100, default 15. The source request fixes sort:inserted_at and order:DESC; these are output/request metadata, not caller options. No search, custom sorting, filtering, all-pages scan or CSV option is accepted. Each call reads only one page.

Output and metric meanings

Success uses MEDIA_COURSE_STATISTICS or MEDIA_SESSION_STATISTICS with statistics, pagination:{page,limit,total}, totalPages of at least 1, the resolved query including fixed sort/order, and periodSelection. The requested page/limit and exact row count implied by total must agree. Invalid or missing source data returns MEDIA_COURSE_STATISTICS_UNVERIFIED instead of an invented empty page. An empty out-of-range page retains its source total.

Resource IDs remain positive decimal strings, including values beyond JavaScript's safe numeric range. Counts remain nonnegative integer strings; seconds remain nonnegative plain decimal strings. These strings are bounded to 128 characters. Preserve leading zeros and decimal precision; do not cast them to numbers, round them to hours, add separators or treat them as mutation selectors without separate discovery. Numeric inputs, signs, exponent notation, grouping and whitespace/control characters are rejected by the response guards. Outer and nested source IDs must match exactly; numeric aliases such as "17" and "017" cannot identify two different rows on one page.

Course completeRate is the source finite nonnegative number. Do not cap it at 100 or recompute it from other counts. For a VOD session, playback contains playCounts, playTimesSeconds and playTimesSecondsAverage as source strings. For a PLAIN session, playbackMetricsApplicable:false and playback:null mean playback is not applicable; hidden source playback values are ignored, not reported as zeros. No session completionCounts, image URL, raw metadata timestamp or unknown field is exposed. Titles retain source text, including empty strings, up to 2000 UTF-16 units without controls. Preserve row order and do not calculate cross-page aggregates.

The result reports targetBinding:scoped-request and periodBinding:request-only. The response has no installed-consumer or requested-period echo: nested ID consistency is not independent ownership or timeframe verification. writesPerformed:false and learnerActivityVerified:false remain explicit, with no revision, creationRevision or task ID. Counts, rates and times do not independently prove attendance, learning, enrollment, completion or playback.

Connection and original-screen limits

The statistics hook is present only when the existing analyticsApiOrigin/PUBL_ANALYTICS_API_ORIGIN setting is explicitly configured. Missing/non-function connection returns MEDIA_COURSE_STATISTICS_HOST_UNAVAILABLE; other collection apps return MEDIA_COURSE_STATISTICS_UNSUPPORTED. Upstream failures and changed context do not become empty success.

The source request helper receives already resolved dates and fixes ANALYTICS GET to /seller/api/v1/overall/serieses for courses or /seller/api/v1/overall/posts for sessions, with string start/end/page/limit and inserted_at/DESC. It requires the explicit existing ANALYTICS origin, exact C00007 installed-consumer scope and existing selected-channel credential, with context checks around the request. There is no API/LIVE fallback, extra grant, arbitrary endpoint or recomputed default period.

The source screen routes are C00007 statistics/series/overall and statistics/posts/overall without query or fragment. The result states consoleFiltersApplied:false: the original screen keeps its period in component state, so a destination does not restore the requested dates or page. Select the returned period and page in that screen before comparing values. Extra row fields, inconsistent projections, historical/error results, revisions or tasks receive no fallback link. Use the returned configured-origin link and its instruction to select the period and page; do not construct a URL from IDs or add date queries.

Omit both dates to request the source default:

{"channelCode":"selected-channel","pAppCode":"C00007","view":{"kind":"course-statistics"}}

Select an explicit past date pair and one session page:

{"channelCode":"selected-channel","pAppCode":"C00007","view":{"kind":"session-statistics","query":{"start":"2026-09-01","end":"2026-09-30","page":2,"limit":30}}}

Neither set measures actual ANALYTICS traffic. The overview and top-five lists use the separate course-overview contract; CSV remains outside these view contracts. This section adds no public tool or task type.

Course overview

The existing getter accepts view:{kind:course-overview,query?} for exact C00007. This is an additional view, not a new tool or task type. It differs from paginated course-statistics/session-statistics and per-student progress.

query accepts only start and end: supply both real YYYY-MM-DD labels or neither. Dates start at 2022-01-01, start must not follow end, their difference must be below 93 days and end cannot exceed the current UTC date. Omission resolves once to UTC today minus 31 days through today and returns periodSelection:source-default; supplied dates return explicit. All six reads receive that same resolved pair. The 31-day difference does not prove backend endpoint inclusivity, aggregation timezone, data freshness or daylight-saving duration. There is no caller page, limit, sort, filter, resource selector or CSV option.

Success returns MEDIA_COURSE_OVERVIEW with overview, resolved query and periodSelection. The overview contains all six source sections:

Counts and times remain strings up to 128 characters, preserving leading zeros and precision. Resource IDs are positive decimal strings, including beyond-safe-integer values. Do not convert through Number, round into hours, recompute rates or derive a complete inventory/aggregate from the top lists. Titles retain source text, including empty strings, up to 2000 UTF-16 units without control characters. Unknown metadata is omitted.

Each ranking must have nonincreasing numeric counts; tied rows keep their source order. Outer/nested resource IDs must match exactly, and numeric aliases such as "17" and "017" cannot identify separate rows in one list. Empty lists are valid, but missing sections or malformed metrics/rankings return MEDIA_COURSE_OVERVIEW_UNVERIFIED. Do not fabricate zero values or infer relationships between independently returned totals and rankings.

The workflow starts six independent reads and waits for all to settle before returning or reporting a failure. Request arrival/completion order is not part of the contract. Any failed request or invalid section prevents partial success. The selected context is rechecked after the requests. Results report targetBinding:scoped-request, periodBinding:request-only, atomicSnapshotVerified:false, consoleFiltersApplied:false, writesPerformed:false and learnerActivityVerified:false. Neither consumer/date identity nor an atomic snapshot is independently echoed by the backend. No edit revision, creationRevision or task ID is issued, and these values do not prove attendance, learning, enrollment, completion or playback.

The physical hook exists only with the existing explicit analyticsApiOrigin/PUBL_ANALYTICS_API_ORIGIN configuration. It uses the current selected-channel credential and exact installed C00007 consumer; context/grant/credential/installation changes suppress success. Missing/non-function hook returns MEDIA_COURSE_OVERVIEW_HOST_UNAVAILABLE, and other apps return MEDIA_COURSE_OVERVIEW_UNSUPPORTED. There is no API/LIVE fallback or new service setting.

The fixed ANALYTICS GET requests use /seller/api/v1/view-counts/sum, watch-times/sum, watch-times/average and complete-rates/average, plus two requests to /seller/api/v1/view-counts. The top-course request fixes group_by:series_id, the top-session request group_by:post_id, and both fix sort:counts, order:DESC and limit:5. These are implementation metadata, not caller-controlled paths or options.

Fresh matching results can return exactly the selected C00007 statistics/overview destination. Common navigation revalidates the resolved period and complete six-section projection, false write/activity/atomic/filter flags and absence of revisions/tasks. Malformed, extra-field, incomplete, inconsistent, historical or error results get no fallback link. Use the returned configured-origin link and select its returned period manually in the original screen; the link has no date query/fragment and does not restore filters.

Illustrative default-period input only:

{"channelCode":"selected-channel","pAppCode":"C00007","view":{"kind":"course-overview"}}

Illustrative explicit-period input; replace the target and date pair with the intended authorized selection:

{"channelCode":"selected-channel","pAppCode":"C00007","view":{"kind":"course-overview","query":{"start":"2026-09-01","end":"2026-09-30"}}}

Shared direct/compact checks use real HttpPublPort with intercepted HTTP. They are source evidence, not actual ANALYTICS calls or same-period console comparison.