{ "item": [ { "name": "v1", "description": "", "item": [ { "name": "client", "description": "", "item": [ { "name": "analytics", "description": "", "item": [ { "name": "status", "description": "", "item": [ { "id": "d7d8bdbd-29e1-4a96-83bc-3b2e848a1484", "name": "Key smoke-test & dataset freshness", "request": { "name": "Key smoke-test & dataset freshness", "description": { "content": "Echoes the authenticated key's identity, name, scopes and expiry, plus a\nper-dataset freshness block (`datasets..latest_date`, the latest\ningested day for the brand). Requires a valid key but no particular scope.\n\nThis endpoint NEVER returns `503`: if the analytics store is unreachable\nthe freshness probe degrades to `datasets: null` while the identity block\nstays intact. Use it as your health check.\n\n`datasets` keys map to the data endpoints as: `daily` →\n`metrics/daily`, `contents` → `metrics/contents`, `users` →\n`users/daily`, `content_engagement` → `users/contents`. A\n`latest_date` of `null` means no data has been ingested for the brand yet.\n", "type": "text/plain" }, "url": { "path": [ "v1", "client", "analytics", "status" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {}, "auth": null }, "response": [ { "id": "986c64c7-0b90-4b27-91fb-ec6cfcd0a555", "name": "The authenticated key context and dataset freshness.", "originalRequest": { "url": { "path": [ "v1", "client", "analytics", "status" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" }, { "disabled": false, "description": { "content": "", "type": "text/plain" }, "key": "X-RateLimit-Limit", "value": "" }, { "disabled": false, "description": { "content": "", "type": "text/plain" }, "key": "X-RateLimit-Remaining", "value": "" }, { "disabled": false, "description": { "content": "", "type": "text/plain" }, "key": "X-RateLimit-Reset", "value": "" } ], "body": "{\n \"brand_id\": \"\",\n \"key_id\": \"\",\n \"name\": \"\",\n \"scopes\": [\n \"\",\n \"\"\n ],\n \"expires_at\": \"\",\n \"datasets\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "bd4fb440-0505-47a4-9670-c9b13c629fc5", "name": "Missing, malformed, expired or revoked key — or a `cfk_` feed token\npresented on this surface.", "originalRequest": { "url": { "path": [ "v1", "client", "analytics", "status" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"code\": \"\",\n \"message\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "f56ebf23-a772-4d00-93bd-4930d129aa8c", "name": "A per-key (120/min) or per-brand (240/min) rate limit was exceeded.\nCarries the `X-RateLimit-*` trio and `Retry-After`.", "originalRequest": { "url": { "path": [ "v1", "client", "analytics", "status" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "Too Many Requests", "code": 429, "header": [ { "key": "Content-Type", "value": "application/json" }, { "disabled": false, "description": { "content": "", "type": "text/plain" }, "key": "Retry-After", "value": "" }, { "disabled": false, "description": { "content": "", "type": "text/plain" }, "key": "X-RateLimit-Limit", "value": "" }, { "disabled": false, "description": { "content": "", "type": "text/plain" }, "key": "X-RateLimit-Remaining", "value": "" }, { "disabled": false, "description": { "content": "", "type": "text/plain" }, "key": "X-RateLimit-Reset", "value": "" } ], "body": "{\n \"code\": \"\",\n \"message\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } } ] }, { "name": "metrics", "description": "", "item": [ { "name": "daily", "description": "", "item": [ { "id": "86c1fe7e-99d6-466b-9183-2c0eb611cdc4", "name": "Brand-level daily aggregates", "request": { "name": "Brand-level daily aggregates", "description": { "content": "Daily learning aggregates from `analytics_daily`, one row per day. Three\nmutually-exclusive granularities:\n\n- **brand-level** (default) — `market` is `null` on every row;\n- **single market** — `market=`; rows for that market only;\n- **per-market breakdown** — `group_by=market`; one row per market per day\n (brand-level rows excluded). `market` and `group_by=market` may not be\n combined (→ `422 validation_failed`).\n\nOffset-paginated (`page`/`per_page`, default 50, cap 200) with an exact\n`total` — the volume is small and bounded (days × markets). Default window\nis the last **30 days** ending yesterday (UTC); the inclusive window may\nnot exceed **366 days** (→ `422 date_range_too_large`).\n", "type": "text/plain" }, "url": { "path": [ "v1", "client", "analytics", "metrics", "daily" ], "host": [ "{{baseUrl}}" ], "query": [ { "disabled": false, "description": { "content": "Inclusive lower day bound (`YYYY-MM-DD`, UTC). Defaults to the dataset's default window before `to`.", "type": "text/plain" }, "key": "from", "value": "" }, { "disabled": false, "description": { "content": "Inclusive upper day bound (`YYYY-MM-DD`, UTC). Defaults to yesterday (J-1).", "type": "text/plain" }, "key": "to", "value": "" }, { "disabled": false, "description": { "content": "A market `tu_id`. Restricts `metrics/daily` to that market. Mutually exclusive with `group_by=market`. Unknown/cross-brand → 404.", "type": "text/plain" }, "key": "market", "value": "" }, { "disabled": false, "description": { "content": "Set to `market` for a per-market breakdown (one row per market per day). Mutually exclusive with `market`. (This can only be one of market)", "type": "text/plain" }, "key": "group_by", "value": "market" }, { "disabled": false, "description": { "content": "1-based page number (offset pagination). Clamped to >= 1.", "type": "text/plain" }, "key": "page", "value": "1" }, { "disabled": false, "description": { "content": "Page size for offset pagination. Clamped to [1, 200].", "type": "text/plain" }, "key": "per_page", "value": "50" } ], "variable": [] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {}, "auth": null }, "response": [ { "id": "5806c3f2-cfba-406f-a8d1-d7db6f33302a", "name": "A page of daily aggregate rows.", "originalRequest": { "url": { "path": [ "v1", "client", "analytics", "metrics", "daily" ], "host": [ "{{baseUrl}}" ], "query": [ { "disabled": false, "description": { "content": "Inclusive lower day bound (`YYYY-MM-DD`, UTC). Defaults to the dataset's default window before `to`.", "type": "text/plain" }, "key": "from", "value": "" }, { "disabled": false, "description": { "content": "Inclusive upper day bound (`YYYY-MM-DD`, UTC). Defaults to yesterday (J-1).", "type": "text/plain" }, "key": "to", "value": "" }, { "disabled": false, "description": { "content": "A market `tu_id`. Restricts `metrics/daily` to that market. Mutually exclusive with `group_by=market`. Unknown/cross-brand → 404.", "type": "text/plain" }, "key": "market", "value": "" }, { "disabled": false, "description": { "content": "Set to `market` for a per-market breakdown (one row per market per day). Mutually exclusive with `market`. (This can only be one of market)", "type": "text/plain" }, "key": "group_by", "value": "market" }, { "disabled": false, "description": { "content": "1-based page number (offset pagination). Clamped to >= 1.", "type": "text/plain" }, "key": "page", "value": "1" }, { "disabled": false, "description": { "content": "Page size for offset pagination. Clamped to [1, 200].", "type": "text/plain" }, "key": "per_page", "value": "50" } ], "variable": [] }, "header": [ { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" }, { "disabled": false, "description": { "content": "", "type": "text/plain" }, "key": "X-RateLimit-Limit", "value": "" }, { "disabled": false, "description": { "content": "", "type": "text/plain" }, "key": "X-RateLimit-Remaining", "value": "" }, { "disabled": false, "description": { "content": "", "type": "text/plain" }, "key": "X-RateLimit-Reset", "value": "" } ], "body": "{\n \"data\": [\n {\n \"date\": \"\",\n \"market\": \"\",\n \"live_content\": {\n \"episodes\": \"\",\n \"programs\": \"\",\n \"quests\": \"\",\n \"products\": \"\"\n },\n \"active_users\": \"\",\n \"totals\": {\n \"views\": \"\",\n \"completions\": \"\",\n \"successes\": \"\",\n \"xp_earned\": \"\",\n \"time_spent_seconds\": \"\"\n },\n \"episodes\": {\n \"views\": \"\",\n \"completions\": \"\",\n \"successes\": \"\",\n \"time_spent_seconds\": \"\",\n \"watch_rate\": \"\",\n \"completion_rate\": \"\",\n \"success_rate\": \"\",\n \"quiz_average_score\": \"\"\n },\n \"programs\": {\n \"views\": \"\",\n \"completions\": \"\",\n \"successes\": \"\",\n \"time_spent_seconds\": \"\",\n \"watch_rate\": \"\",\n \"completion_rate\": \"\",\n \"success_rate\": \"\",\n \"quiz_average_score\": \"\"\n },\n \"quests\": {\n \"views\": \"\",\n \"completions\": \"\",\n \"successes\": \"\",\n \"time_spent_seconds\": \"\",\n \"watch_rate\": \"\",\n \"completion_rate\": \"\",\n \"success_rate\": \"\",\n \"quiz_average_score\": \"\"\n },\n \"overall_completion_rate\": \"\",\n \"cumulative\": {\n \"views\": \"\",\n \"completions\": \"\",\n \"successes\": \"\",\n \"xp_earned\": \"\"\n }\n },\n {\n \"date\": \"\",\n \"market\": \"\",\n \"live_content\": {\n \"episodes\": \"\",\n \"programs\": \"\",\n \"quests\": \"\",\n \"products\": \"\"\n },\n \"active_users\": \"\",\n \"totals\": {\n \"views\": \"\",\n \"completions\": \"\",\n \"successes\": \"\",\n \"xp_earned\": \"\",\n \"time_spent_seconds\": \"\"\n },\n \"episodes\": {\n \"views\": \"\",\n \"completions\": \"\",\n \"successes\": \"\",\n \"time_spent_seconds\": \"\",\n \"watch_rate\": \"\",\n \"completion_rate\": \"\",\n \"success_rate\": \"\",\n \"quiz_average_score\": \"\"\n },\n \"programs\": {\n \"views\": \"\",\n \"completions\": \"\",\n \"successes\": \"\",\n \"time_spent_seconds\": \"\",\n \"watch_rate\": \"\",\n \"completion_rate\": \"\",\n \"success_rate\": \"\",\n \"quiz_average_score\": \"\"\n },\n \"quests\": {\n \"views\": \"\",\n \"completions\": \"\",\n \"successes\": \"\",\n \"time_spent_seconds\": \"\",\n \"watch_rate\": \"\",\n \"completion_rate\": \"\",\n \"success_rate\": \"\",\n \"quiz_average_score\": \"\"\n },\n \"overall_completion_rate\": \"\",\n \"cumulative\": {\n \"views\": \"\",\n \"completions\": \"\",\n \"successes\": \"\",\n \"xp_earned\": \"\"\n }\n }\n ],\n \"meta\": {\n \"current_page\": \"\",\n \"per_page\": \"\",\n \"total\": \"\",\n \"last_page\": \"\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "1f88e04d-7ce8-43e0-8ea6-6c84e309fa29", "name": "Missing, malformed, expired or revoked key — or a `cfk_` feed token\npresented on this surface.", "originalRequest": { "url": { "path": [ "v1", "client", "analytics", "metrics", "daily" ], "host": [ "{{baseUrl}}" ], "query": [ { "disabled": false, "description": { "content": "Inclusive lower day bound (`YYYY-MM-DD`, UTC). Defaults to the dataset's default window before `to`.", "type": "text/plain" }, "key": "from", "value": "" }, { "disabled": false, "description": { "content": "Inclusive upper day bound (`YYYY-MM-DD`, UTC). Defaults to yesterday (J-1).", "type": "text/plain" }, "key": "to", "value": "" }, { "disabled": false, "description": { "content": "A market `tu_id`. Restricts `metrics/daily` to that market. Mutually exclusive with `group_by=market`. Unknown/cross-brand → 404.", "type": "text/plain" }, "key": "market", "value": "" }, { "disabled": false, "description": { "content": "Set to `market` for a per-market breakdown (one row per market per day). Mutually exclusive with `market`. (This can only be one of market)", "type": "text/plain" }, "key": "group_by", "value": "market" }, { "disabled": false, "description": { "content": "1-based page number (offset pagination). Clamped to >= 1.", "type": "text/plain" }, "key": "page", "value": "1" }, { "disabled": false, "description": { "content": "Page size for offset pagination. Clamped to [1, 200].", "type": "text/plain" }, "key": "per_page", "value": "50" } ], "variable": [] }, "header": [ { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"code\": \"\",\n \"message\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "a6973c19-acb1-40bd-987c-3a34eee933c4", "name": "The key is valid but lacks the required analytics scope.", "originalRequest": { "url": { "path": [ "v1", "client", "analytics", "metrics", "daily" ], "host": [ "{{baseUrl}}" ], "query": [ { "disabled": false, "description": { "content": "Inclusive lower day bound (`YYYY-MM-DD`, UTC). Defaults to the dataset's default window before `to`.", "type": "text/plain" }, "key": "from", "value": "" }, { "disabled": false, "description": { "content": "Inclusive upper day bound (`YYYY-MM-DD`, UTC). Defaults to yesterday (J-1).", "type": "text/plain" }, "key": "to", "value": "" }, { "disabled": false, "description": { "content": "A market `tu_id`. Restricts `metrics/daily` to that market. Mutually exclusive with `group_by=market`. Unknown/cross-brand → 404.", "type": "text/plain" }, "key": "market", "value": "" }, { "disabled": false, "description": { "content": "Set to `market` for a per-market breakdown (one row per market per day). Mutually exclusive with `market`. (This can only be one of market)", "type": "text/plain" }, "key": "group_by", "value": "market" }, { "disabled": false, "description": { "content": "1-based page number (offset pagination). Clamped to >= 1.", "type": "text/plain" }, "key": "page", "value": "1" }, { "disabled": false, "description": { "content": "Page size for offset pagination. Clamped to [1, 200].", "type": "text/plain" }, "key": "per_page", "value": "50" } ], "variable": [] }, "header": [ { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "Forbidden", "code": 403, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"code\": \"\",\n \"message\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "e2134b1c-857b-4a49-adb5-07f7c2be82fa", "name": "The addressed market / content / user does not exist or belongs to another brand.", "originalRequest": { "url": { "path": [ "v1", "client", "analytics", "metrics", "daily" ], "host": [ "{{baseUrl}}" ], "query": [ { "disabled": false, "description": { "content": "Inclusive lower day bound (`YYYY-MM-DD`, UTC). Defaults to the dataset's default window before `to`.", "type": "text/plain" }, "key": "from", "value": "" }, { "disabled": false, "description": { "content": "Inclusive upper day bound (`YYYY-MM-DD`, UTC). Defaults to yesterday (J-1).", "type": "text/plain" }, "key": "to", "value": "" }, { "disabled": false, "description": { "content": "A market `tu_id`. Restricts `metrics/daily` to that market. Mutually exclusive with `group_by=market`. Unknown/cross-brand → 404.", "type": "text/plain" }, "key": "market", "value": "" }, { "disabled": false, "description": { "content": "Set to `market` for a per-market breakdown (one row per market per day). Mutually exclusive with `market`. (This can only be one of market)", "type": "text/plain" }, "key": "group_by", "value": "market" }, { "disabled": false, "description": { "content": "1-based page number (offset pagination). Clamped to >= 1.", "type": "text/plain" }, "key": "page", "value": "1" }, { "disabled": false, "description": { "content": "Page size for offset pagination. Clamped to [1, 200].", "type": "text/plain" }, "key": "per_page", "value": "50" } ], "variable": [] }, "header": [ { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "Not Found", "code": 404, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"code\": \"\",\n \"message\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "eeab4a2c-826c-4dab-9904-eba1967bad60", "name": "Either standard field validation failed (`validation_failed`, carries an\n`errors` map) or the requested date window exceeds the dataset cap\n(`date_range_too_large`, no `errors` map — the message states the cap).", "originalRequest": { "url": { "path": [ "v1", "client", "analytics", "metrics", "daily" ], "host": [ "{{baseUrl}}" ], "query": [ { "disabled": false, "description": { "content": "Inclusive lower day bound (`YYYY-MM-DD`, UTC). Defaults to the dataset's default window before `to`.", "type": "text/plain" }, "key": "from", "value": "" }, { "disabled": false, "description": { "content": "Inclusive upper day bound (`YYYY-MM-DD`, UTC). Defaults to yesterday (J-1).", "type": "text/plain" }, "key": "to", "value": "" }, { "disabled": false, "description": { "content": "A market `tu_id`. Restricts `metrics/daily` to that market. Mutually exclusive with `group_by=market`. Unknown/cross-brand → 404.", "type": "text/plain" }, "key": "market", "value": "" }, { "disabled": false, "description": { "content": "Set to `market` for a per-market breakdown (one row per market per day). Mutually exclusive with `market`. (This can only be one of market)", "type": "text/plain" }, "key": "group_by", "value": "market" }, { "disabled": false, "description": { "content": "1-based page number (offset pagination). Clamped to >= 1.", "type": "text/plain" }, "key": "page", "value": "1" }, { "disabled": false, "description": { "content": "Page size for offset pagination. Clamped to [1, 200].", "type": "text/plain" }, "key": "per_page", "value": "50" } ], "variable": [] }, "header": [ { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "Unprocessable Entity (WebDAV) (RFC 4918)", "code": 422, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"code\": \"\",\n \"message\": \"\",\n \"errors\": {\n \"key_0\": [\n \"\",\n \"\"\n ],\n \"key_1\": [\n \"\",\n \"\"\n ]\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "f98c109d-ed5f-49a6-9861-fbf65b1f620b", "name": "A per-key (120/min) or per-brand (240/min) rate limit was exceeded.\nCarries the `X-RateLimit-*` trio and `Retry-After`.", "originalRequest": { "url": { "path": [ "v1", "client", "analytics", "metrics", "daily" ], "host": [ "{{baseUrl}}" ], "query": [ { "disabled": false, "description": { "content": "Inclusive lower day bound (`YYYY-MM-DD`, UTC). Defaults to the dataset's default window before `to`.", "type": "text/plain" }, "key": "from", "value": "" }, { "disabled": false, "description": { "content": "Inclusive upper day bound (`YYYY-MM-DD`, UTC). Defaults to yesterday (J-1).", "type": "text/plain" }, "key": "to", "value": "" }, { "disabled": false, "description": { "content": "A market `tu_id`. Restricts `metrics/daily` to that market. Mutually exclusive with `group_by=market`. Unknown/cross-brand → 404.", "type": "text/plain" }, "key": "market", "value": "" }, { "disabled": false, "description": { "content": "Set to `market` for a per-market breakdown (one row per market per day). Mutually exclusive with `market`. (This can only be one of market)", "type": "text/plain" }, "key": "group_by", "value": "market" }, { "disabled": false, "description": { "content": "1-based page number (offset pagination). Clamped to >= 1.", "type": "text/plain" }, "key": "page", "value": "1" }, { "disabled": false, "description": { "content": "Page size for offset pagination. Clamped to [1, 200].", "type": "text/plain" }, "key": "per_page", "value": "50" } ], "variable": [] }, "header": [ { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "Too Many Requests", "code": 429, "header": [ { "key": "Content-Type", "value": "application/json" }, { "disabled": false, "description": { "content": "", "type": "text/plain" }, "key": "Retry-After", "value": "" }, { "disabled": false, "description": { "content": "", "type": "text/plain" }, "key": "X-RateLimit-Limit", "value": "" }, { "disabled": false, "description": { "content": "", "type": "text/plain" }, "key": "X-RateLimit-Remaining", "value": "" }, { "disabled": false, "description": { "content": "", "type": "text/plain" }, "key": "X-RateLimit-Reset", "value": "" } ], "body": "{\n \"code\": \"\",\n \"message\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "7ee69608-0e6c-43e9-895d-2d611d255b8d", "name": "The analytics backing store is temporarily unreachable. This is NEVER a\nsilent empty page — retry after the hinted delay. The `status` endpoint\ndoes not emit this (it degrades to `datasets: null`).", "originalRequest": { "url": { "path": [ "v1", "client", "analytics", "metrics", "daily" ], "host": [ "{{baseUrl}}" ], "query": [ { "disabled": false, "description": { "content": "Inclusive lower day bound (`YYYY-MM-DD`, UTC). Defaults to the dataset's default window before `to`.", "type": "text/plain" }, "key": "from", "value": "" }, { "disabled": false, "description": { "content": "Inclusive upper day bound (`YYYY-MM-DD`, UTC). Defaults to yesterday (J-1).", "type": "text/plain" }, "key": "to", "value": "" }, { "disabled": false, "description": { "content": "A market `tu_id`. Restricts `metrics/daily` to that market. Mutually exclusive with `group_by=market`. Unknown/cross-brand → 404.", "type": "text/plain" }, "key": "market", "value": "" }, { "disabled": false, "description": { "content": "Set to `market` for a per-market breakdown (one row per market per day). Mutually exclusive with `market`. (This can only be one of market)", "type": "text/plain" }, "key": "group_by", "value": "market" }, { "disabled": false, "description": { "content": "1-based page number (offset pagination). Clamped to >= 1.", "type": "text/plain" }, "key": "page", "value": "1" }, { "disabled": false, "description": { "content": "Page size for offset pagination. Clamped to [1, 200].", "type": "text/plain" }, "key": "per_page", "value": "50" } ], "variable": [] }, "header": [ { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "Service Unavailable", "code": 503, "header": [ { "key": "Content-Type", "value": "application/json" }, { "disabled": false, "description": { "content": "", "type": "text/plain" }, "key": "Retry-After", "value": "" } ], "body": "{\n \"code\": \"\",\n \"message\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } } ] }, { "name": "contents", "description": "", "item": [ { "id": "617fe8ee-65ac-4bd2-9863-b028cfac4536", "name": "Content-level metrics (brand-global)", "request": { "name": "Content-level metrics (brand-global)", "description": { "content": "Content-level rows from `learning_snapshots`, brand-global (market and POS\naggregates are excluded). Cursor-paginated on the `(content_ref_id, date)`\nkeyset. Default window is the last **30 days** ending yesterday (UTC); the\ninclusive window may not exceed **92 days** (→ `422 date_range_too_large`).\n\nOptional filters: `type` (`episode`|`program`) narrows to that content\ntype; `content=` reverses to a single content and REQUIRES\n`type` (a bare `content` is `422`). An unknown/cross-brand `content` is a\nflat `404`. Each row's `content` is the resolved `{ tu_id, type, name }`\nidentity, or `null` when the reference is orphaned/cross-brand (the row is\nstill returned). `market` and `pos` are always `null` on this dataset.\n", "type": "text/plain" }, "url": { "path": [ "v1", "client", "analytics", "metrics", "contents" ], "host": [ "{{baseUrl}}" ], "query": [ { "disabled": false, "description": { "content": "Inclusive lower day bound (`YYYY-MM-DD`, UTC). Defaults to the dataset's default window before `to`.", "type": "text/plain" }, "key": "from", "value": "" }, { "disabled": false, "description": { "content": "Inclusive upper day bound (`YYYY-MM-DD`, UTC). Defaults to yesterday (J-1).", "type": "text/plain" }, "key": "to", "value": "" }, { "disabled": false, "description": { "content": "Content-type filter. REQUIRED when `content` is supplied. (This can only be one of episode,program)", "type": "text/plain" }, "key": "type", "value": "episode" }, { "disabled": false, "description": { "content": "A content `tu_id`. Requires `type`. Unknown/cross-brand → 404.", "type": "text/plain" }, "key": "content", "value": "" }, { "disabled": false, "description": { "content": "Page size for cursor pagination. Clamped to [1, 500].", "type": "text/plain" }, "key": "per_page", "value": "100" }, { "disabled": false, "description": { "content": "Opaque, encrypted pagination cursor taken verbatim from a previous\nresponse's `meta.next_cursor`. Do not decode, construct or mutate it — a\ntampered or foreign cursor is rejected with `400 invalid_cursor`.\n", "type": "text/plain" }, "key": "cursor", "value": "" } ], "variable": [] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {}, "auth": null }, "response": [ { "id": "6d9e8986-a568-434f-be25-b2ff1d7be75c", "name": "A cursor page of content-level rows.", "originalRequest": { "url": { "path": [ "v1", "client", "analytics", "metrics", "contents" ], "host": [ "{{baseUrl}}" ], "query": [ { "disabled": false, "description": { "content": "Inclusive lower day bound (`YYYY-MM-DD`, UTC). Defaults to the dataset's default window before `to`.", "type": "text/plain" }, "key": "from", "value": "" }, { "disabled": false, "description": { "content": "Inclusive upper day bound (`YYYY-MM-DD`, UTC). Defaults to yesterday (J-1).", "type": "text/plain" }, "key": "to", "value": "" }, { "disabled": false, "description": { "content": "Content-type filter. REQUIRED when `content` is supplied. (This can only be one of episode,program)", "type": "text/plain" }, "key": "type", "value": "episode" }, { "disabled": false, "description": { "content": "A content `tu_id`. Requires `type`. Unknown/cross-brand → 404.", "type": "text/plain" }, "key": "content", "value": "" }, { "disabled": false, "description": { "content": "Page size for cursor pagination. Clamped to [1, 500].", "type": "text/plain" }, "key": "per_page", "value": "100" }, { "disabled": false, "description": { "content": "Opaque, encrypted pagination cursor taken verbatim from a previous\nresponse's `meta.next_cursor`. Do not decode, construct or mutate it — a\ntampered or foreign cursor is rejected with `400 invalid_cursor`.\n", "type": "text/plain" }, "key": "cursor", "value": "" } ], "variable": [] }, "header": [ { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" }, { "disabled": false, "description": { "content": "", "type": "text/plain" }, "key": "X-RateLimit-Limit", "value": "" }, { "disabled": false, "description": { "content": "", "type": "text/plain" }, "key": "X-RateLimit-Remaining", "value": "" }, { "disabled": false, "description": { "content": "", "type": "text/plain" }, "key": "X-RateLimit-Reset", "value": "" } ], "body": "{\n \"data\": [\n {\n \"date\": \"\",\n \"content\": \"\",\n \"market\": \"\",\n \"pos\": \"\",\n \"metrics\": {\n \"views\": \"\",\n \"unique_views\": \"\",\n \"completions\": \"\",\n \"successes\": \"\",\n \"active_users\": \"\",\n \"total_users\": \"\",\n \"engagement_rate\": \"\",\n \"xp_earned\": \"\",\n \"time_spent_seconds\": \"\",\n \"questions_count\": \"\",\n \"quiz_average_score\": \"\"\n },\n \"cumulative\": {\n \"views\": \"\",\n \"completions\": \"\",\n \"successes\": \"\",\n \"watch_rate\": \"\",\n \"completion_rate\": \"\",\n \"success_rate\": \"\",\n \"quiz_average_score\": \"\"\n }\n },\n {\n \"date\": \"\",\n \"content\": \"\",\n \"market\": \"\",\n \"pos\": \"\",\n \"metrics\": {\n \"views\": \"\",\n \"unique_views\": \"\",\n \"completions\": \"\",\n \"successes\": \"\",\n \"active_users\": \"\",\n \"total_users\": \"\",\n \"engagement_rate\": \"\",\n \"xp_earned\": \"\",\n \"time_spent_seconds\": \"\",\n \"questions_count\": \"\",\n \"quiz_average_score\": \"\"\n },\n \"cumulative\": {\n \"views\": \"\",\n \"completions\": \"\",\n \"successes\": \"\",\n \"watch_rate\": \"\",\n \"completion_rate\": \"\",\n \"success_rate\": \"\",\n \"quiz_average_score\": \"\"\n }\n }\n ],\n \"meta\": {\n \"per_page\": \"\",\n \"next_cursor\": \"\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "00fb2cf0-f8de-452e-92e2-c074357c48b1", "name": "The `cursor` query parameter is malformed, tampered or unsupported.", "originalRequest": { "url": { "path": [ "v1", "client", "analytics", "metrics", "contents" ], "host": [ "{{baseUrl}}" ], "query": [ { "disabled": false, "description": { "content": "Inclusive lower day bound (`YYYY-MM-DD`, UTC). Defaults to the dataset's default window before `to`.", "type": "text/plain" }, "key": "from", "value": "" }, { "disabled": false, "description": { "content": "Inclusive upper day bound (`YYYY-MM-DD`, UTC). Defaults to yesterday (J-1).", "type": "text/plain" }, "key": "to", "value": "" }, { "disabled": false, "description": { "content": "Content-type filter. REQUIRED when `content` is supplied. (This can only be one of episode,program)", "type": "text/plain" }, "key": "type", "value": "episode" }, { "disabled": false, "description": { "content": "A content `tu_id`. Requires `type`. Unknown/cross-brand → 404.", "type": "text/plain" }, "key": "content", "value": "" }, { "disabled": false, "description": { "content": "Page size for cursor pagination. Clamped to [1, 500].", "type": "text/plain" }, "key": "per_page", "value": "100" }, { "disabled": false, "description": { "content": "Opaque, encrypted pagination cursor taken verbatim from a previous\nresponse's `meta.next_cursor`. Do not decode, construct or mutate it — a\ntampered or foreign cursor is rejected with `400 invalid_cursor`.\n", "type": "text/plain" }, "key": "cursor", "value": "" } ], "variable": [] }, "header": [ { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "Bad Request", "code": 400, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"code\": \"\",\n \"message\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "b3135194-a27e-497c-a413-b540cc9fb743", "name": "Missing, malformed, expired or revoked key — or a `cfk_` feed token\npresented on this surface.", "originalRequest": { "url": { "path": [ "v1", "client", "analytics", "metrics", "contents" ], "host": [ "{{baseUrl}}" ], "query": [ { "disabled": false, "description": { "content": "Inclusive lower day bound (`YYYY-MM-DD`, UTC). Defaults to the dataset's default window before `to`.", "type": "text/plain" }, "key": "from", "value": "" }, { "disabled": false, "description": { "content": "Inclusive upper day bound (`YYYY-MM-DD`, UTC). Defaults to yesterday (J-1).", "type": "text/plain" }, "key": "to", "value": "" }, { "disabled": false, "description": { "content": "Content-type filter. REQUIRED when `content` is supplied. (This can only be one of episode,program)", "type": "text/plain" }, "key": "type", "value": "episode" }, { "disabled": false, "description": { "content": "A content `tu_id`. Requires `type`. Unknown/cross-brand → 404.", "type": "text/plain" }, "key": "content", "value": "" }, { "disabled": false, "description": { "content": "Page size for cursor pagination. Clamped to [1, 500].", "type": "text/plain" }, "key": "per_page", "value": "100" }, { "disabled": false, "description": { "content": "Opaque, encrypted pagination cursor taken verbatim from a previous\nresponse's `meta.next_cursor`. Do not decode, construct or mutate it — a\ntampered or foreign cursor is rejected with `400 invalid_cursor`.\n", "type": "text/plain" }, "key": "cursor", "value": "" } ], "variable": [] }, "header": [ { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"code\": \"\",\n \"message\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "379f77e0-439c-4232-9891-1a1d0c886e8b", "name": "The key is valid but lacks the required analytics scope.", "originalRequest": { "url": { "path": [ "v1", "client", "analytics", "metrics", "contents" ], "host": [ "{{baseUrl}}" ], "query": [ { "disabled": false, "description": { "content": "Inclusive lower day bound (`YYYY-MM-DD`, UTC). Defaults to the dataset's default window before `to`.", "type": "text/plain" }, "key": "from", "value": "" }, { "disabled": false, "description": { "content": "Inclusive upper day bound (`YYYY-MM-DD`, UTC). Defaults to yesterday (J-1).", "type": "text/plain" }, "key": "to", "value": "" }, { "disabled": false, "description": { "content": "Content-type filter. REQUIRED when `content` is supplied. (This can only be one of episode,program)", "type": "text/plain" }, "key": "type", "value": "episode" }, { "disabled": false, "description": { "content": "A content `tu_id`. Requires `type`. Unknown/cross-brand → 404.", "type": "text/plain" }, "key": "content", "value": "" }, { "disabled": false, "description": { "content": "Page size for cursor pagination. Clamped to [1, 500].", "type": "text/plain" }, "key": "per_page", "value": "100" }, { "disabled": false, "description": { "content": "Opaque, encrypted pagination cursor taken verbatim from a previous\nresponse's `meta.next_cursor`. Do not decode, construct or mutate it — a\ntampered or foreign cursor is rejected with `400 invalid_cursor`.\n", "type": "text/plain" }, "key": "cursor", "value": "" } ], "variable": [] }, "header": [ { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "Forbidden", "code": 403, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"code\": \"\",\n \"message\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "9548cd94-4601-474b-9299-04584888f305", "name": "The addressed market / content / user does not exist or belongs to another brand.", "originalRequest": { "url": { "path": [ "v1", "client", "analytics", "metrics", "contents" ], "host": [ "{{baseUrl}}" ], "query": [ { "disabled": false, "description": { "content": "Inclusive lower day bound (`YYYY-MM-DD`, UTC). Defaults to the dataset's default window before `to`.", "type": "text/plain" }, "key": "from", "value": "" }, { "disabled": false, "description": { "content": "Inclusive upper day bound (`YYYY-MM-DD`, UTC). Defaults to yesterday (J-1).", "type": "text/plain" }, "key": "to", "value": "" }, { "disabled": false, "description": { "content": "Content-type filter. REQUIRED when `content` is supplied. (This can only be one of episode,program)", "type": "text/plain" }, "key": "type", "value": "episode" }, { "disabled": false, "description": { "content": "A content `tu_id`. Requires `type`. Unknown/cross-brand → 404.", "type": "text/plain" }, "key": "content", "value": "" }, { "disabled": false, "description": { "content": "Page size for cursor pagination. Clamped to [1, 500].", "type": "text/plain" }, "key": "per_page", "value": "100" }, { "disabled": false, "description": { "content": "Opaque, encrypted pagination cursor taken verbatim from a previous\nresponse's `meta.next_cursor`. Do not decode, construct or mutate it — a\ntampered or foreign cursor is rejected with `400 invalid_cursor`.\n", "type": "text/plain" }, "key": "cursor", "value": "" } ], "variable": [] }, "header": [ { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "Not Found", "code": 404, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"code\": \"\",\n \"message\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "d12a7fef-733f-44cd-9e80-424c3afd6fc8", "name": "Either standard field validation failed (`validation_failed`, carries an\n`errors` map) or the requested date window exceeds the dataset cap\n(`date_range_too_large`, no `errors` map — the message states the cap).", "originalRequest": { "url": { "path": [ "v1", "client", "analytics", "metrics", "contents" ], "host": [ "{{baseUrl}}" ], "query": [ { "disabled": false, "description": { "content": "Inclusive lower day bound (`YYYY-MM-DD`, UTC). Defaults to the dataset's default window before `to`.", "type": "text/plain" }, "key": "from", "value": "" }, { "disabled": false, "description": { "content": "Inclusive upper day bound (`YYYY-MM-DD`, UTC). Defaults to yesterday (J-1).", "type": "text/plain" }, "key": "to", "value": "" }, { "disabled": false, "description": { "content": "Content-type filter. REQUIRED when `content` is supplied. (This can only be one of episode,program)", "type": "text/plain" }, "key": "type", "value": "episode" }, { "disabled": false, "description": { "content": "A content `tu_id`. Requires `type`. Unknown/cross-brand → 404.", "type": "text/plain" }, "key": "content", "value": "" }, { "disabled": false, "description": { "content": "Page size for cursor pagination. Clamped to [1, 500].", "type": "text/plain" }, "key": "per_page", "value": "100" }, { "disabled": false, "description": { "content": "Opaque, encrypted pagination cursor taken verbatim from a previous\nresponse's `meta.next_cursor`. Do not decode, construct or mutate it — a\ntampered or foreign cursor is rejected with `400 invalid_cursor`.\n", "type": "text/plain" }, "key": "cursor", "value": "" } ], "variable": [] }, "header": [ { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "Unprocessable Entity (WebDAV) (RFC 4918)", "code": 422, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"code\": \"\",\n \"message\": \"\",\n \"errors\": {\n \"key_0\": [\n \"\",\n \"\"\n ],\n \"key_1\": [\n \"\",\n \"\"\n ]\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "4f95b5a9-0391-4200-bfdc-57ecd3e06d2f", "name": "A per-key (120/min) or per-brand (240/min) rate limit was exceeded.\nCarries the `X-RateLimit-*` trio and `Retry-After`.", "originalRequest": { "url": { "path": [ "v1", "client", "analytics", "metrics", "contents" ], "host": [ "{{baseUrl}}" ], "query": [ { "disabled": false, "description": { "content": "Inclusive lower day bound (`YYYY-MM-DD`, UTC). Defaults to the dataset's default window before `to`.", "type": "text/plain" }, "key": "from", "value": "" }, { "disabled": false, "description": { "content": "Inclusive upper day bound (`YYYY-MM-DD`, UTC). Defaults to yesterday (J-1).", "type": "text/plain" }, "key": "to", "value": "" }, { "disabled": false, "description": { "content": "Content-type filter. REQUIRED when `content` is supplied. (This can only be one of episode,program)", "type": "text/plain" }, "key": "type", "value": "episode" }, { "disabled": false, "description": { "content": "A content `tu_id`. Requires `type`. Unknown/cross-brand → 404.", "type": "text/plain" }, "key": "content", "value": "" }, { "disabled": false, "description": { "content": "Page size for cursor pagination. Clamped to [1, 500].", "type": "text/plain" }, "key": "per_page", "value": "100" }, { "disabled": false, "description": { "content": "Opaque, encrypted pagination cursor taken verbatim from a previous\nresponse's `meta.next_cursor`. Do not decode, construct or mutate it — a\ntampered or foreign cursor is rejected with `400 invalid_cursor`.\n", "type": "text/plain" }, "key": "cursor", "value": "" } ], "variable": [] }, "header": [ { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "Too Many Requests", "code": 429, "header": [ { "key": "Content-Type", "value": "application/json" }, { "disabled": false, "description": { "content": "", "type": "text/plain" }, "key": "Retry-After", "value": "" }, { "disabled": false, "description": { "content": "", "type": "text/plain" }, "key": "X-RateLimit-Limit", "value": "" }, { "disabled": false, "description": { "content": "", "type": "text/plain" }, "key": "X-RateLimit-Remaining", "value": "" }, { "disabled": false, "description": { "content": "", "type": "text/plain" }, "key": "X-RateLimit-Reset", "value": "" } ], "body": "{\n \"code\": \"\",\n \"message\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "8f7a3a67-07ea-4c51-9320-8479299d4f86", "name": "The analytics backing store is temporarily unreachable. This is NEVER a\nsilent empty page — retry after the hinted delay. The `status` endpoint\ndoes not emit this (it degrades to `datasets: null`).", "originalRequest": { "url": { "path": [ "v1", "client", "analytics", "metrics", "contents" ], "host": [ "{{baseUrl}}" ], "query": [ { "disabled": false, "description": { "content": "Inclusive lower day bound (`YYYY-MM-DD`, UTC). Defaults to the dataset's default window before `to`.", "type": "text/plain" }, "key": "from", "value": "" }, { "disabled": false, "description": { "content": "Inclusive upper day bound (`YYYY-MM-DD`, UTC). Defaults to yesterday (J-1).", "type": "text/plain" }, "key": "to", "value": "" }, { "disabled": false, "description": { "content": "Content-type filter. REQUIRED when `content` is supplied. (This can only be one of episode,program)", "type": "text/plain" }, "key": "type", "value": "episode" }, { "disabled": false, "description": { "content": "A content `tu_id`. Requires `type`. Unknown/cross-brand → 404.", "type": "text/plain" }, "key": "content", "value": "" }, { "disabled": false, "description": { "content": "Page size for cursor pagination. Clamped to [1, 500].", "type": "text/plain" }, "key": "per_page", "value": "100" }, { "disabled": false, "description": { "content": "Opaque, encrypted pagination cursor taken verbatim from a previous\nresponse's `meta.next_cursor`. Do not decode, construct or mutate it — a\ntampered or foreign cursor is rejected with `400 invalid_cursor`.\n", "type": "text/plain" }, "key": "cursor", "value": "" } ], "variable": [] }, "header": [ { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "Service Unavailable", "code": 503, "header": [ { "key": "Content-Type", "value": "application/json" }, { "disabled": false, "description": { "content": "", "type": "text/plain" }, "key": "Retry-After", "value": "" } ], "body": "{\n \"code\": \"\",\n \"message\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } } ] } ] }, { "name": "users", "description": "", "item": [ { "name": "daily", "description": "", "item": [ { "id": "253fcc06-03d1-401b-b998-2bc25d858319", "name": "Pseudonymised per-user daily rows", "request": { "name": "Pseudonymised per-user daily rows", "description": { "content": "Brand-level per-user daily rows from `learning_users`, pseudonymised: the\nONLY user identifier is the public `tu_id`. Cursor-paginated on the\n`(user_id, date)` keyset. Default window is the last **30 days** ending\nyesterday (UTC); the inclusive window may not exceed **92 days**\n(→ `422 date_range_too_large`).\n\nOptional `user=` filter (unknown/excluded/cross-brand → an\nindistinguishable flat `404`). `market` and `pos` are always `null`\n(brand-level rows).\n\n**Privacy — sparse pages.** A per-page defensive filter re-applies the\nanalytics-eligibility + brand-membership rules, so a user excluded AFTER\nthe nightly aggregation is dropped from `data`. The cursor still advances\non the last RAW row, so a page may legally be `data: []` with a non-null\n`next_cursor`. Keep following `next_cursor` until it is `null`.\n", "type": "text/plain" }, "url": { "path": [ "v1", "client", "analytics", "users", "daily" ], "host": [ "{{baseUrl}}" ], "query": [ { "disabled": false, "description": { "content": "Inclusive lower day bound (`YYYY-MM-DD`, UTC). Defaults to the dataset's default window before `to`.", "type": "text/plain" }, "key": "from", "value": "" }, { "disabled": false, "description": { "content": "Inclusive upper day bound (`YYYY-MM-DD`, UTC). Defaults to yesterday (J-1).", "type": "text/plain" }, "key": "to", "value": "" }, { "disabled": false, "description": { "content": "A user `tu_id`. Unknown/excluded/cross-brand → an indistinguishable 404.", "type": "text/plain" }, "key": "user", "value": "" }, { "disabled": false, "description": { "content": "Page size for cursor pagination. Clamped to [1, 500].", "type": "text/plain" }, "key": "per_page", "value": "100" }, { "disabled": false, "description": { "content": "Opaque, encrypted pagination cursor taken verbatim from a previous\nresponse's `meta.next_cursor`. Do not decode, construct or mutate it — a\ntampered or foreign cursor is rejected with `400 invalid_cursor`.\n", "type": "text/plain" }, "key": "cursor", "value": "" } ], "variable": [] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {}, "auth": null }, "response": [ { "id": "d4119d09-e175-4abc-8985-349b0c9aea84", "name": "A cursor page of pseudonymised per-user daily rows.", "originalRequest": { "url": { "path": [ "v1", "client", "analytics", "users", "daily" ], "host": [ "{{baseUrl}}" ], "query": [ { "disabled": false, "description": { "content": "Inclusive lower day bound (`YYYY-MM-DD`, UTC). Defaults to the dataset's default window before `to`.", "type": "text/plain" }, "key": "from", "value": "" }, { "disabled": false, "description": { "content": "Inclusive upper day bound (`YYYY-MM-DD`, UTC). Defaults to yesterday (J-1).", "type": "text/plain" }, "key": "to", "value": "" }, { "disabled": false, "description": { "content": "A user `tu_id`. Unknown/excluded/cross-brand → an indistinguishable 404.", "type": "text/plain" }, "key": "user", "value": "" }, { "disabled": false, "description": { "content": "Page size for cursor pagination. Clamped to [1, 500].", "type": "text/plain" }, "key": "per_page", "value": "100" }, { "disabled": false, "description": { "content": "Opaque, encrypted pagination cursor taken verbatim from a previous\nresponse's `meta.next_cursor`. Do not decode, construct or mutate it — a\ntampered or foreign cursor is rejected with `400 invalid_cursor`.\n", "type": "text/plain" }, "key": "cursor", "value": "" } ], "variable": [] }, "header": [ { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" }, { "disabled": false, "description": { "content": "", "type": "text/plain" }, "key": "X-RateLimit-Limit", "value": "" }, { "disabled": false, "description": { "content": "", "type": "text/plain" }, "key": "X-RateLimit-Remaining", "value": "" }, { "disabled": false, "description": { "content": "", "type": "text/plain" }, "key": "X-RateLimit-Reset", "value": "" } ], "body": "{\n \"data\": [\n {\n \"date\": \"\",\n \"user\": {\n \"tu_id\": \"\"\n },\n \"market\": \"\",\n \"pos\": \"\",\n \"metrics\": {\n \"views\": \"\",\n \"completions\": \"\",\n \"successes\": \"\",\n \"xp_earned\": \"\",\n \"time_spent_seconds\": \"\",\n \"overall_score\": \"\",\n \"episodes\": {\n \"views\": \"\",\n \"completions\": \"\",\n \"successes\": \"\"\n },\n \"programs\": {\n \"views\": \"\",\n \"completions\": \"\",\n \"successes\": \"\"\n },\n \"quests\": {\n \"views\": \"\",\n \"completions\": \"\",\n \"successes\": \"\"\n }\n },\n \"cumulative\": {\n \"views\": \"\",\n \"completions\": \"\",\n \"successes\": \"\",\n \"episodes\": {\n \"views\": \"\",\n \"completions\": \"\",\n \"successes\": \"\"\n },\n \"programs\": {\n \"views\": \"\",\n \"completions\": \"\",\n \"successes\": \"\"\n },\n \"quests\": {\n \"views\": \"\",\n \"completions\": \"\",\n \"successes\": \"\"\n }\n }\n },\n {\n \"date\": \"\",\n \"user\": {\n \"tu_id\": \"\"\n },\n \"market\": \"\",\n \"pos\": \"\",\n \"metrics\": {\n \"views\": \"\",\n \"completions\": \"\",\n \"successes\": \"\",\n \"xp_earned\": \"\",\n \"time_spent_seconds\": \"\",\n \"overall_score\": \"\",\n \"episodes\": {\n \"views\": \"\",\n \"completions\": \"\",\n \"successes\": \"\"\n },\n \"programs\": {\n \"views\": \"\",\n \"completions\": \"\",\n \"successes\": \"\"\n },\n \"quests\": {\n \"views\": \"\",\n \"completions\": \"\",\n \"successes\": \"\"\n }\n },\n \"cumulative\": {\n \"views\": \"\",\n \"completions\": \"\",\n \"successes\": \"\",\n \"episodes\": {\n \"views\": \"\",\n \"completions\": \"\",\n \"successes\": \"\"\n },\n \"programs\": {\n \"views\": \"\",\n \"completions\": \"\",\n \"successes\": \"\"\n },\n \"quests\": {\n \"views\": \"\",\n \"completions\": \"\",\n \"successes\": \"\"\n }\n }\n }\n ],\n \"meta\": {\n \"per_page\": \"\",\n \"next_cursor\": \"\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "ac9d1963-2076-423e-8594-d0ab714b6e05", "name": "The `cursor` query parameter is malformed, tampered or unsupported.", "originalRequest": { "url": { "path": [ "v1", "client", "analytics", "users", "daily" ], "host": [ "{{baseUrl}}" ], "query": [ { "disabled": false, "description": { "content": "Inclusive lower day bound (`YYYY-MM-DD`, UTC). Defaults to the dataset's default window before `to`.", "type": "text/plain" }, "key": "from", "value": "" }, { "disabled": false, "description": { "content": "Inclusive upper day bound (`YYYY-MM-DD`, UTC). Defaults to yesterday (J-1).", "type": "text/plain" }, "key": "to", "value": "" }, { "disabled": false, "description": { "content": "A user `tu_id`. Unknown/excluded/cross-brand → an indistinguishable 404.", "type": "text/plain" }, "key": "user", "value": "" }, { "disabled": false, "description": { "content": "Page size for cursor pagination. Clamped to [1, 500].", "type": "text/plain" }, "key": "per_page", "value": "100" }, { "disabled": false, "description": { "content": "Opaque, encrypted pagination cursor taken verbatim from a previous\nresponse's `meta.next_cursor`. Do not decode, construct or mutate it — a\ntampered or foreign cursor is rejected with `400 invalid_cursor`.\n", "type": "text/plain" }, "key": "cursor", "value": "" } ], "variable": [] }, "header": [ { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "Bad Request", "code": 400, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"code\": \"\",\n \"message\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "3e38ca51-f231-4ead-ba90-05654d30cecd", "name": "Missing, malformed, expired or revoked key — or a `cfk_` feed token\npresented on this surface.", "originalRequest": { "url": { "path": [ "v1", "client", "analytics", "users", "daily" ], "host": [ "{{baseUrl}}" ], "query": [ { "disabled": false, "description": { "content": "Inclusive lower day bound (`YYYY-MM-DD`, UTC). Defaults to the dataset's default window before `to`.", "type": "text/plain" }, "key": "from", "value": "" }, { "disabled": false, "description": { "content": "Inclusive upper day bound (`YYYY-MM-DD`, UTC). Defaults to yesterday (J-1).", "type": "text/plain" }, "key": "to", "value": "" }, { "disabled": false, "description": { "content": "A user `tu_id`. Unknown/excluded/cross-brand → an indistinguishable 404.", "type": "text/plain" }, "key": "user", "value": "" }, { "disabled": false, "description": { "content": "Page size for cursor pagination. Clamped to [1, 500].", "type": "text/plain" }, "key": "per_page", "value": "100" }, { "disabled": false, "description": { "content": "Opaque, encrypted pagination cursor taken verbatim from a previous\nresponse's `meta.next_cursor`. Do not decode, construct or mutate it — a\ntampered or foreign cursor is rejected with `400 invalid_cursor`.\n", "type": "text/plain" }, "key": "cursor", "value": "" } ], "variable": [] }, "header": [ { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"code\": \"\",\n \"message\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "da0e1557-ab20-4f46-b01b-28c155fc3319", "name": "The key is valid but lacks the required analytics scope.", "originalRequest": { "url": { "path": [ "v1", "client", "analytics", "users", "daily" ], "host": [ "{{baseUrl}}" ], "query": [ { "disabled": false, "description": { "content": "Inclusive lower day bound (`YYYY-MM-DD`, UTC). Defaults to the dataset's default window before `to`.", "type": "text/plain" }, "key": "from", "value": "" }, { "disabled": false, "description": { "content": "Inclusive upper day bound (`YYYY-MM-DD`, UTC). Defaults to yesterday (J-1).", "type": "text/plain" }, "key": "to", "value": "" }, { "disabled": false, "description": { "content": "A user `tu_id`. Unknown/excluded/cross-brand → an indistinguishable 404.", "type": "text/plain" }, "key": "user", "value": "" }, { "disabled": false, "description": { "content": "Page size for cursor pagination. Clamped to [1, 500].", "type": "text/plain" }, "key": "per_page", "value": "100" }, { "disabled": false, "description": { "content": "Opaque, encrypted pagination cursor taken verbatim from a previous\nresponse's `meta.next_cursor`. Do not decode, construct or mutate it — a\ntampered or foreign cursor is rejected with `400 invalid_cursor`.\n", "type": "text/plain" }, "key": "cursor", "value": "" } ], "variable": [] }, "header": [ { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "Forbidden", "code": 403, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"code\": \"\",\n \"message\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "b261f6c9-ec74-41c4-8e09-11143d4d4df1", "name": "The addressed market / content / user does not exist or belongs to another brand.", "originalRequest": { "url": { "path": [ "v1", "client", "analytics", "users", "daily" ], "host": [ "{{baseUrl}}" ], "query": [ { "disabled": false, "description": { "content": "Inclusive lower day bound (`YYYY-MM-DD`, UTC). Defaults to the dataset's default window before `to`.", "type": "text/plain" }, "key": "from", "value": "" }, { "disabled": false, "description": { "content": "Inclusive upper day bound (`YYYY-MM-DD`, UTC). Defaults to yesterday (J-1).", "type": "text/plain" }, "key": "to", "value": "" }, { "disabled": false, "description": { "content": "A user `tu_id`. Unknown/excluded/cross-brand → an indistinguishable 404.", "type": "text/plain" }, "key": "user", "value": "" }, { "disabled": false, "description": { "content": "Page size for cursor pagination. Clamped to [1, 500].", "type": "text/plain" }, "key": "per_page", "value": "100" }, { "disabled": false, "description": { "content": "Opaque, encrypted pagination cursor taken verbatim from a previous\nresponse's `meta.next_cursor`. Do not decode, construct or mutate it — a\ntampered or foreign cursor is rejected with `400 invalid_cursor`.\n", "type": "text/plain" }, "key": "cursor", "value": "" } ], "variable": [] }, "header": [ { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "Not Found", "code": 404, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"code\": \"\",\n \"message\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "21a9763e-4a86-47e0-8329-ab498f9e22f9", "name": "Either standard field validation failed (`validation_failed`, carries an\n`errors` map) or the requested date window exceeds the dataset cap\n(`date_range_too_large`, no `errors` map — the message states the cap).", "originalRequest": { "url": { "path": [ "v1", "client", "analytics", "users", "daily" ], "host": [ "{{baseUrl}}" ], "query": [ { "disabled": false, "description": { "content": "Inclusive lower day bound (`YYYY-MM-DD`, UTC). Defaults to the dataset's default window before `to`.", "type": "text/plain" }, "key": "from", "value": "" }, { "disabled": false, "description": { "content": "Inclusive upper day bound (`YYYY-MM-DD`, UTC). Defaults to yesterday (J-1).", "type": "text/plain" }, "key": "to", "value": "" }, { "disabled": false, "description": { "content": "A user `tu_id`. Unknown/excluded/cross-brand → an indistinguishable 404.", "type": "text/plain" }, "key": "user", "value": "" }, { "disabled": false, "description": { "content": "Page size for cursor pagination. Clamped to [1, 500].", "type": "text/plain" }, "key": "per_page", "value": "100" }, { "disabled": false, "description": { "content": "Opaque, encrypted pagination cursor taken verbatim from a previous\nresponse's `meta.next_cursor`. Do not decode, construct or mutate it — a\ntampered or foreign cursor is rejected with `400 invalid_cursor`.\n", "type": "text/plain" }, "key": "cursor", "value": "" } ], "variable": [] }, "header": [ { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "Unprocessable Entity (WebDAV) (RFC 4918)", "code": 422, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"code\": \"\",\n \"message\": \"\",\n \"errors\": {\n \"key_0\": [\n \"\",\n \"\"\n ],\n \"key_1\": [\n \"\",\n \"\"\n ]\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "d4f545b9-2c12-4d0a-ba0a-b97530c73bf5", "name": "A per-key (120/min) or per-brand (240/min) rate limit was exceeded.\nCarries the `X-RateLimit-*` trio and `Retry-After`.", "originalRequest": { "url": { "path": [ "v1", "client", "analytics", "users", "daily" ], "host": [ "{{baseUrl}}" ], "query": [ { "disabled": false, "description": { "content": "Inclusive lower day bound (`YYYY-MM-DD`, UTC). Defaults to the dataset's default window before `to`.", "type": "text/plain" }, "key": "from", "value": "" }, { "disabled": false, "description": { "content": "Inclusive upper day bound (`YYYY-MM-DD`, UTC). Defaults to yesterday (J-1).", "type": "text/plain" }, "key": "to", "value": "" }, { "disabled": false, "description": { "content": "A user `tu_id`. Unknown/excluded/cross-brand → an indistinguishable 404.", "type": "text/plain" }, "key": "user", "value": "" }, { "disabled": false, "description": { "content": "Page size for cursor pagination. Clamped to [1, 500].", "type": "text/plain" }, "key": "per_page", "value": "100" }, { "disabled": false, "description": { "content": "Opaque, encrypted pagination cursor taken verbatim from a previous\nresponse's `meta.next_cursor`. Do not decode, construct or mutate it — a\ntampered or foreign cursor is rejected with `400 invalid_cursor`.\n", "type": "text/plain" }, "key": "cursor", "value": "" } ], "variable": [] }, "header": [ { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "Too Many Requests", "code": 429, "header": [ { "key": "Content-Type", "value": "application/json" }, { "disabled": false, "description": { "content": "", "type": "text/plain" }, "key": "Retry-After", "value": "" }, { "disabled": false, "description": { "content": "", "type": "text/plain" }, "key": "X-RateLimit-Limit", "value": "" }, { "disabled": false, "description": { "content": "", "type": "text/plain" }, "key": "X-RateLimit-Remaining", "value": "" }, { "disabled": false, "description": { "content": "", "type": "text/plain" }, "key": "X-RateLimit-Reset", "value": "" } ], "body": "{\n \"code\": \"\",\n \"message\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "1f9625f3-9641-419b-9308-be9b3e1d7158", "name": "The analytics backing store is temporarily unreachable. This is NEVER a\nsilent empty page — retry after the hinted delay. The `status` endpoint\ndoes not emit this (it degrades to `datasets: null`).", "originalRequest": { "url": { "path": [ "v1", "client", "analytics", "users", "daily" ], "host": [ "{{baseUrl}}" ], "query": [ { "disabled": false, "description": { "content": "Inclusive lower day bound (`YYYY-MM-DD`, UTC). Defaults to the dataset's default window before `to`.", "type": "text/plain" }, "key": "from", "value": "" }, { "disabled": false, "description": { "content": "Inclusive upper day bound (`YYYY-MM-DD`, UTC). Defaults to yesterday (J-1).", "type": "text/plain" }, "key": "to", "value": "" }, { "disabled": false, "description": { "content": "A user `tu_id`. Unknown/excluded/cross-brand → an indistinguishable 404.", "type": "text/plain" }, "key": "user", "value": "" }, { "disabled": false, "description": { "content": "Page size for cursor pagination. Clamped to [1, 500].", "type": "text/plain" }, "key": "per_page", "value": "100" }, { "disabled": false, "description": { "content": "Opaque, encrypted pagination cursor taken verbatim from a previous\nresponse's `meta.next_cursor`. Do not decode, construct or mutate it — a\ntampered or foreign cursor is rejected with `400 invalid_cursor`.\n", "type": "text/plain" }, "key": "cursor", "value": "" } ], "variable": [] }, "header": [ { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "Service Unavailable", "code": 503, "header": [ { "key": "Content-Type", "value": "application/json" }, { "disabled": false, "description": { "content": "", "type": "text/plain" }, "key": "Retry-After", "value": "" } ], "body": "{\n \"code\": \"\",\n \"message\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } } ] }, { "name": "contents", "description": "", "item": [ { "id": "6bd2452b-6837-47cf-a3ee-1f92089ad373", "name": "Pseudonymised user × content sync rows", "request": { "name": "Pseudonymised user × content sync rows", "description": { "content": "User × content rows from `learning_content_users`, pseudonymised to\n`tu_id`. This is a high-volume SYNC dataset. Cursor-paginated on the\n`(content_ref_id, date, user_id)` keyset. Default window is the last\n**7 days** ending yesterday (UTC); the inclusive window may not exceed\n**92 days** (→ `422 date_range_too_large`).\n\nOptional filters: `user=` (flat `404` on miss),\n`content=` + `type` (`type` REQUIRED with `content`;\nflat `404` on miss), and `completed` (boolean) which is applied\nstore-side so pages stay full. The `content` block carries `{ tu_id,\ntype }` ONLY (no `name` label on this dataset), or `null` for an\norphaned/cross-brand reference. The same sparse-page rule as `users/daily`\napplies (defensive per-page PII drops; follow `next_cursor` to `null`).\n", "type": "text/plain" }, "url": { "path": [ "v1", "client", "analytics", "users", "contents" ], "host": [ "{{baseUrl}}" ], "query": [ { "disabled": false, "description": { "content": "Inclusive lower day bound (`YYYY-MM-DD`, UTC). Defaults to the dataset's default window before `to`.", "type": "text/plain" }, "key": "from", "value": "" }, { "disabled": false, "description": { "content": "Inclusive upper day bound (`YYYY-MM-DD`, UTC). Defaults to yesterday (J-1).", "type": "text/plain" }, "key": "to", "value": "" }, { "disabled": false, "description": { "content": "A user `tu_id`. Unknown/excluded/cross-brand → an indistinguishable 404.", "type": "text/plain" }, "key": "user", "value": "" }, { "disabled": false, "description": { "content": "Content-type filter. REQUIRED when `content` is supplied. (This can only be one of episode,program)", "type": "text/plain" }, "key": "type", "value": "episode" }, { "disabled": false, "description": { "content": "A content `tu_id`. Requires `type`. Unknown/cross-brand → 404.", "type": "text/plain" }, "key": "content", "value": "" }, { "disabled": false, "description": { "content": "Filter `users/contents` rows by completion (applied store-side so pages stay full).", "type": "text/plain" }, "key": "completed", "value": "" }, { "disabled": false, "description": { "content": "Page size for cursor pagination. Clamped to [1, 500].", "type": "text/plain" }, "key": "per_page", "value": "100" }, { "disabled": false, "description": { "content": "Opaque, encrypted pagination cursor taken verbatim from a previous\nresponse's `meta.next_cursor`. Do not decode, construct or mutate it — a\ntampered or foreign cursor is rejected with `400 invalid_cursor`.\n", "type": "text/plain" }, "key": "cursor", "value": "" } ], "variable": [] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {}, "auth": null }, "response": [ { "id": "1e6ec0b3-9659-4247-84b3-da3c10c2fda0", "name": "A cursor page of pseudonymised user × content rows.", "originalRequest": { "url": { "path": [ "v1", "client", "analytics", "users", "contents" ], "host": [ "{{baseUrl}}" ], "query": [ { "disabled": false, "description": { "content": "Inclusive lower day bound (`YYYY-MM-DD`, UTC). Defaults to the dataset's default window before `to`.", "type": "text/plain" }, "key": "from", "value": "" }, { "disabled": false, "description": { "content": "Inclusive upper day bound (`YYYY-MM-DD`, UTC). Defaults to yesterday (J-1).", "type": "text/plain" }, "key": "to", "value": "" }, { "disabled": false, "description": { "content": "A user `tu_id`. Unknown/excluded/cross-brand → an indistinguishable 404.", "type": "text/plain" }, "key": "user", "value": "" }, { "disabled": false, "description": { "content": "Content-type filter. REQUIRED when `content` is supplied. (This can only be one of episode,program)", "type": "text/plain" }, "key": "type", "value": "episode" }, { "disabled": false, "description": { "content": "A content `tu_id`. Requires `type`. Unknown/cross-brand → 404.", "type": "text/plain" }, "key": "content", "value": "" }, { "disabled": false, "description": { "content": "Filter `users/contents` rows by completion (applied store-side so pages stay full).", "type": "text/plain" }, "key": "completed", "value": "" }, { "disabled": false, "description": { "content": "Page size for cursor pagination. Clamped to [1, 500].", "type": "text/plain" }, "key": "per_page", "value": "100" }, { "disabled": false, "description": { "content": "Opaque, encrypted pagination cursor taken verbatim from a previous\nresponse's `meta.next_cursor`. Do not decode, construct or mutate it — a\ntampered or foreign cursor is rejected with `400 invalid_cursor`.\n", "type": "text/plain" }, "key": "cursor", "value": "" } ], "variable": [] }, "header": [ { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" }, { "disabled": false, "description": { "content": "", "type": "text/plain" }, "key": "X-RateLimit-Limit", "value": "" }, { "disabled": false, "description": { "content": "", "type": "text/plain" }, "key": "X-RateLimit-Remaining", "value": "" }, { "disabled": false, "description": { "content": "", "type": "text/plain" }, "key": "X-RateLimit-Reset", "value": "" } ], "body": "{\n \"data\": [\n {\n \"date\": \"\",\n \"user\": {\n \"tu_id\": \"\"\n },\n \"content\": \"\",\n \"metrics\": {\n \"views\": \"\",\n \"xp_earned\": \"\",\n \"time_spent_seconds\": \"\",\n \"is_completed\": \"\",\n \"is_successful\": \"\",\n \"questions_count\": \"\",\n \"quiz_average_score\": \"\",\n \"quiz_completion_rate\": \"\"\n },\n \"cumulative\": {\n \"views\": \"\",\n \"xp_earned\": \"\",\n \"time_spent_seconds\": \"\",\n \"quiz_average_score\": \"\"\n }\n },\n {\n \"date\": \"\",\n \"user\": {\n \"tu_id\": \"\"\n },\n \"content\": \"\",\n \"metrics\": {\n \"views\": \"\",\n \"xp_earned\": \"\",\n \"time_spent_seconds\": \"\",\n \"is_completed\": \"\",\n \"is_successful\": \"\",\n \"questions_count\": \"\",\n \"quiz_average_score\": \"\",\n \"quiz_completion_rate\": \"\"\n },\n \"cumulative\": {\n \"views\": \"\",\n \"xp_earned\": \"\",\n \"time_spent_seconds\": \"\",\n \"quiz_average_score\": \"\"\n }\n }\n ],\n \"meta\": {\n \"per_page\": \"\",\n \"next_cursor\": \"\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "70ca0bdd-98a2-44e7-85da-1f13d07f6496", "name": "The `cursor` query parameter is malformed, tampered or unsupported.", "originalRequest": { "url": { "path": [ "v1", "client", "analytics", "users", "contents" ], "host": [ "{{baseUrl}}" ], "query": [ { "disabled": false, "description": { "content": "Inclusive lower day bound (`YYYY-MM-DD`, UTC). Defaults to the dataset's default window before `to`.", "type": "text/plain" }, "key": "from", "value": "" }, { "disabled": false, "description": { "content": "Inclusive upper day bound (`YYYY-MM-DD`, UTC). Defaults to yesterday (J-1).", "type": "text/plain" }, "key": "to", "value": "" }, { "disabled": false, "description": { "content": "A user `tu_id`. Unknown/excluded/cross-brand → an indistinguishable 404.", "type": "text/plain" }, "key": "user", "value": "" }, { "disabled": false, "description": { "content": "Content-type filter. REQUIRED when `content` is supplied. (This can only be one of episode,program)", "type": "text/plain" }, "key": "type", "value": "episode" }, { "disabled": false, "description": { "content": "A content `tu_id`. Requires `type`. Unknown/cross-brand → 404.", "type": "text/plain" }, "key": "content", "value": "" }, { "disabled": false, "description": { "content": "Filter `users/contents` rows by completion (applied store-side so pages stay full).", "type": "text/plain" }, "key": "completed", "value": "" }, { "disabled": false, "description": { "content": "Page size for cursor pagination. Clamped to [1, 500].", "type": "text/plain" }, "key": "per_page", "value": "100" }, { "disabled": false, "description": { "content": "Opaque, encrypted pagination cursor taken verbatim from a previous\nresponse's `meta.next_cursor`. Do not decode, construct or mutate it — a\ntampered or foreign cursor is rejected with `400 invalid_cursor`.\n", "type": "text/plain" }, "key": "cursor", "value": "" } ], "variable": [] }, "header": [ { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "Bad Request", "code": 400, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"code\": \"\",\n \"message\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "98db377f-47b5-4fdb-8ce8-adb7190ff6e0", "name": "Missing, malformed, expired or revoked key — or a `cfk_` feed token\npresented on this surface.", "originalRequest": { "url": { "path": [ "v1", "client", "analytics", "users", "contents" ], "host": [ "{{baseUrl}}" ], "query": [ { "disabled": false, "description": { "content": "Inclusive lower day bound (`YYYY-MM-DD`, UTC). Defaults to the dataset's default window before `to`.", "type": "text/plain" }, "key": "from", "value": "" }, { "disabled": false, "description": { "content": "Inclusive upper day bound (`YYYY-MM-DD`, UTC). Defaults to yesterday (J-1).", "type": "text/plain" }, "key": "to", "value": "" }, { "disabled": false, "description": { "content": "A user `tu_id`. Unknown/excluded/cross-brand → an indistinguishable 404.", "type": "text/plain" }, "key": "user", "value": "" }, { "disabled": false, "description": { "content": "Content-type filter. REQUIRED when `content` is supplied. (This can only be one of episode,program)", "type": "text/plain" }, "key": "type", "value": "episode" }, { "disabled": false, "description": { "content": "A content `tu_id`. Requires `type`. Unknown/cross-brand → 404.", "type": "text/plain" }, "key": "content", "value": "" }, { "disabled": false, "description": { "content": "Filter `users/contents` rows by completion (applied store-side so pages stay full).", "type": "text/plain" }, "key": "completed", "value": "" }, { "disabled": false, "description": { "content": "Page size for cursor pagination. Clamped to [1, 500].", "type": "text/plain" }, "key": "per_page", "value": "100" }, { "disabled": false, "description": { "content": "Opaque, encrypted pagination cursor taken verbatim from a previous\nresponse's `meta.next_cursor`. Do not decode, construct or mutate it — a\ntampered or foreign cursor is rejected with `400 invalid_cursor`.\n", "type": "text/plain" }, "key": "cursor", "value": "" } ], "variable": [] }, "header": [ { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"code\": \"\",\n \"message\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "7977c77e-a127-46eb-aac5-14a13af4bfb9", "name": "The key is valid but lacks the required analytics scope.", "originalRequest": { "url": { "path": [ "v1", "client", "analytics", "users", "contents" ], "host": [ "{{baseUrl}}" ], "query": [ { "disabled": false, "description": { "content": "Inclusive lower day bound (`YYYY-MM-DD`, UTC). Defaults to the dataset's default window before `to`.", "type": "text/plain" }, "key": "from", "value": "" }, { "disabled": false, "description": { "content": "Inclusive upper day bound (`YYYY-MM-DD`, UTC). Defaults to yesterday (J-1).", "type": "text/plain" }, "key": "to", "value": "" }, { "disabled": false, "description": { "content": "A user `tu_id`. Unknown/excluded/cross-brand → an indistinguishable 404.", "type": "text/plain" }, "key": "user", "value": "" }, { "disabled": false, "description": { "content": "Content-type filter. REQUIRED when `content` is supplied. (This can only be one of episode,program)", "type": "text/plain" }, "key": "type", "value": "episode" }, { "disabled": false, "description": { "content": "A content `tu_id`. Requires `type`. Unknown/cross-brand → 404.", "type": "text/plain" }, "key": "content", "value": "" }, { "disabled": false, "description": { "content": "Filter `users/contents` rows by completion (applied store-side so pages stay full).", "type": "text/plain" }, "key": "completed", "value": "" }, { "disabled": false, "description": { "content": "Page size for cursor pagination. Clamped to [1, 500].", "type": "text/plain" }, "key": "per_page", "value": "100" }, { "disabled": false, "description": { "content": "Opaque, encrypted pagination cursor taken verbatim from a previous\nresponse's `meta.next_cursor`. Do not decode, construct or mutate it — a\ntampered or foreign cursor is rejected with `400 invalid_cursor`.\n", "type": "text/plain" }, "key": "cursor", "value": "" } ], "variable": [] }, "header": [ { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "Forbidden", "code": 403, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"code\": \"\",\n \"message\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "486b6114-6979-4dfd-bb1b-444cd1e5e1b5", "name": "The addressed market / content / user does not exist or belongs to another brand.", "originalRequest": { "url": { "path": [ "v1", "client", "analytics", "users", "contents" ], "host": [ "{{baseUrl}}" ], "query": [ { "disabled": false, "description": { "content": "Inclusive lower day bound (`YYYY-MM-DD`, UTC). Defaults to the dataset's default window before `to`.", "type": "text/plain" }, "key": "from", "value": "" }, { "disabled": false, "description": { "content": "Inclusive upper day bound (`YYYY-MM-DD`, UTC). Defaults to yesterday (J-1).", "type": "text/plain" }, "key": "to", "value": "" }, { "disabled": false, "description": { "content": "A user `tu_id`. Unknown/excluded/cross-brand → an indistinguishable 404.", "type": "text/plain" }, "key": "user", "value": "" }, { "disabled": false, "description": { "content": "Content-type filter. REQUIRED when `content` is supplied. (This can only be one of episode,program)", "type": "text/plain" }, "key": "type", "value": "episode" }, { "disabled": false, "description": { "content": "A content `tu_id`. Requires `type`. Unknown/cross-brand → 404.", "type": "text/plain" }, "key": "content", "value": "" }, { "disabled": false, "description": { "content": "Filter `users/contents` rows by completion (applied store-side so pages stay full).", "type": "text/plain" }, "key": "completed", "value": "" }, { "disabled": false, "description": { "content": "Page size for cursor pagination. Clamped to [1, 500].", "type": "text/plain" }, "key": "per_page", "value": "100" }, { "disabled": false, "description": { "content": "Opaque, encrypted pagination cursor taken verbatim from a previous\nresponse's `meta.next_cursor`. Do not decode, construct or mutate it — a\ntampered or foreign cursor is rejected with `400 invalid_cursor`.\n", "type": "text/plain" }, "key": "cursor", "value": "" } ], "variable": [] }, "header": [ { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "Not Found", "code": 404, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"code\": \"\",\n \"message\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "6d3821db-cbd3-4c4b-8bba-a6f41bbd3add", "name": "Either standard field validation failed (`validation_failed`, carries an\n`errors` map) or the requested date window exceeds the dataset cap\n(`date_range_too_large`, no `errors` map — the message states the cap).", "originalRequest": { "url": { "path": [ "v1", "client", "analytics", "users", "contents" ], "host": [ "{{baseUrl}}" ], "query": [ { "disabled": false, "description": { "content": "Inclusive lower day bound (`YYYY-MM-DD`, UTC). Defaults to the dataset's default window before `to`.", "type": "text/plain" }, "key": "from", "value": "" }, { "disabled": false, "description": { "content": "Inclusive upper day bound (`YYYY-MM-DD`, UTC). Defaults to yesterday (J-1).", "type": "text/plain" }, "key": "to", "value": "" }, { "disabled": false, "description": { "content": "A user `tu_id`. Unknown/excluded/cross-brand → an indistinguishable 404.", "type": "text/plain" }, "key": "user", "value": "" }, { "disabled": false, "description": { "content": "Content-type filter. REQUIRED when `content` is supplied. (This can only be one of episode,program)", "type": "text/plain" }, "key": "type", "value": "episode" }, { "disabled": false, "description": { "content": "A content `tu_id`. Requires `type`. Unknown/cross-brand → 404.", "type": "text/plain" }, "key": "content", "value": "" }, { "disabled": false, "description": { "content": "Filter `users/contents` rows by completion (applied store-side so pages stay full).", "type": "text/plain" }, "key": "completed", "value": "" }, { "disabled": false, "description": { "content": "Page size for cursor pagination. Clamped to [1, 500].", "type": "text/plain" }, "key": "per_page", "value": "100" }, { "disabled": false, "description": { "content": "Opaque, encrypted pagination cursor taken verbatim from a previous\nresponse's `meta.next_cursor`. Do not decode, construct or mutate it — a\ntampered or foreign cursor is rejected with `400 invalid_cursor`.\n", "type": "text/plain" }, "key": "cursor", "value": "" } ], "variable": [] }, "header": [ { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "Unprocessable Entity (WebDAV) (RFC 4918)", "code": 422, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"code\": \"\",\n \"message\": \"\",\n \"errors\": {\n \"key_0\": [\n \"\",\n \"\"\n ],\n \"key_1\": [\n \"\",\n \"\"\n ]\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "f4943203-37cf-4af1-934d-3bb8b6cdfcf6", "name": "A per-key (120/min) or per-brand (240/min) rate limit was exceeded.\nCarries the `X-RateLimit-*` trio and `Retry-After`.", "originalRequest": { "url": { "path": [ "v1", "client", "analytics", "users", "contents" ], "host": [ "{{baseUrl}}" ], "query": [ { "disabled": false, "description": { "content": "Inclusive lower day bound (`YYYY-MM-DD`, UTC). Defaults to the dataset's default window before `to`.", "type": "text/plain" }, "key": "from", "value": "" }, { "disabled": false, "description": { "content": "Inclusive upper day bound (`YYYY-MM-DD`, UTC). Defaults to yesterday (J-1).", "type": "text/plain" }, "key": "to", "value": "" }, { "disabled": false, "description": { "content": "A user `tu_id`. Unknown/excluded/cross-brand → an indistinguishable 404.", "type": "text/plain" }, "key": "user", "value": "" }, { "disabled": false, "description": { "content": "Content-type filter. REQUIRED when `content` is supplied. (This can only be one of episode,program)", "type": "text/plain" }, "key": "type", "value": "episode" }, { "disabled": false, "description": { "content": "A content `tu_id`. Requires `type`. Unknown/cross-brand → 404.", "type": "text/plain" }, "key": "content", "value": "" }, { "disabled": false, "description": { "content": "Filter `users/contents` rows by completion (applied store-side so pages stay full).", "type": "text/plain" }, "key": "completed", "value": "" }, { "disabled": false, "description": { "content": "Page size for cursor pagination. Clamped to [1, 500].", "type": "text/plain" }, "key": "per_page", "value": "100" }, { "disabled": false, "description": { "content": "Opaque, encrypted pagination cursor taken verbatim from a previous\nresponse's `meta.next_cursor`. Do not decode, construct or mutate it — a\ntampered or foreign cursor is rejected with `400 invalid_cursor`.\n", "type": "text/plain" }, "key": "cursor", "value": "" } ], "variable": [] }, "header": [ { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "Too Many Requests", "code": 429, "header": [ { "key": "Content-Type", "value": "application/json" }, { "disabled": false, "description": { "content": "", "type": "text/plain" }, "key": "Retry-After", "value": "" }, { "disabled": false, "description": { "content": "", "type": "text/plain" }, "key": "X-RateLimit-Limit", "value": "" }, { "disabled": false, "description": { "content": "", "type": "text/plain" }, "key": "X-RateLimit-Remaining", "value": "" }, { "disabled": false, "description": { "content": "", "type": "text/plain" }, "key": "X-RateLimit-Reset", "value": "" } ], "body": "{\n \"code\": \"\",\n \"message\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "2f1844f1-7401-4859-b595-0bb3e8a6fbac", "name": "The analytics backing store is temporarily unreachable. This is NEVER a\nsilent empty page — retry after the hinted delay. The `status` endpoint\ndoes not emit this (it degrades to `datasets: null`).", "originalRequest": { "url": { "path": [ "v1", "client", "analytics", "users", "contents" ], "host": [ "{{baseUrl}}" ], "query": [ { "disabled": false, "description": { "content": "Inclusive lower day bound (`YYYY-MM-DD`, UTC). Defaults to the dataset's default window before `to`.", "type": "text/plain" }, "key": "from", "value": "" }, { "disabled": false, "description": { "content": "Inclusive upper day bound (`YYYY-MM-DD`, UTC). Defaults to yesterday (J-1).", "type": "text/plain" }, "key": "to", "value": "" }, { "disabled": false, "description": { "content": "A user `tu_id`. Unknown/excluded/cross-brand → an indistinguishable 404.", "type": "text/plain" }, "key": "user", "value": "" }, { "disabled": false, "description": { "content": "Content-type filter. REQUIRED when `content` is supplied. (This can only be one of episode,program)", "type": "text/plain" }, "key": "type", "value": "episode" }, { "disabled": false, "description": { "content": "A content `tu_id`. Requires `type`. Unknown/cross-brand → 404.", "type": "text/plain" }, "key": "content", "value": "" }, { "disabled": false, "description": { "content": "Filter `users/contents` rows by completion (applied store-side so pages stay full).", "type": "text/plain" }, "key": "completed", "value": "" }, { "disabled": false, "description": { "content": "Page size for cursor pagination. Clamped to [1, 500].", "type": "text/plain" }, "key": "per_page", "value": "100" }, { "disabled": false, "description": { "content": "Opaque, encrypted pagination cursor taken verbatim from a previous\nresponse's `meta.next_cursor`. Do not decode, construct or mutate it — a\ntampered or foreign cursor is rejected with `400 invalid_cursor`.\n", "type": "text/plain" }, "key": "cursor", "value": "" } ], "variable": [] }, "header": [ { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "Service Unavailable", "code": 503, "header": [ { "key": "Content-Type", "value": "application/json" }, { "disabled": false, "description": { "content": "", "type": "text/plain" }, "key": "Retry-After", "value": "" } ], "body": "{\n \"code\": \"\",\n \"message\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } } ] } ] } ] } ] } ] } ], "auth": { "type": "bearer", "bearer": [ { "type": "any", "value": "{{bearerToken}}", "key": "token" } ] }, "event": [], "variable": [ { "key": "env", "value": "staging" }, { "key": "baseUrl", "value": "https://api.{{env}}.tolduntold.com" } ], "info": { "_postman_id": "bd498ddd-c336-4a88-9b7d-4df15fc743f3", "name": "ToldUntold Client API — Analytics", "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json", "description": { "content": "Machine-to-machine REST API letting a brand's BI / ERP / HRIS systems pull\nits ToldUntold learning analytics: brand-level daily aggregates, content-level\nmetrics, and pseudonymised user-level rows.\n\n## Authentication\nBearer authentication with a `tuk_` Client API key\n(`tuk_.`), issued by a ToldUntold super-admin — the SAME key\ntype as the Catalog surface. A single key can carry catalog and analytics\nscopes together. Legacy feed tokens (`cfk_`) are NOT valid and are rejected\nwith `401`.\n\n## Scopes\n- `analytics.metrics:read` — the aggregate datasets (no user dimension):\n `metrics/daily`, `metrics/contents`.\n- `analytics.users:read` — the pseudonymised user-level datasets:\n `users/daily`, `users/contents`. It is NOT implied by\n `analytics.metrics:read`; a key needs it explicitly.\n\n## Conventions\n- **Errors** use a flat envelope `{ \"code\", \"message\", \"errors\"? }` where\n `code` is a stable machine-readable string.\n- **Offset lists** (`metrics/daily`) return `{ \"data\": [...], \"meta\": {...} }`\n with `page`/`per_page` pagination (`per_page` default 50, hard cap 200) and\n an exact `total`.\n- **Cursor lists** (`metrics/contents`, `users/daily`, `users/contents`)\n return `{ \"data\": [...], \"meta\": { \"per_page\", \"next_cursor\" } }`. The\n cursor is opaque and encrypted; there is no `total`. Follow `next_cursor`\n until it is `null`.\n- **Dates** are `YYYY-MM-DD` (UTC). `from`/`to` are inclusive day bounds.\n- **Rates & scores** are floats on a 0–100 scale. **Durations** are integer\n seconds (`*_seconds`).\n- **Rate limits** are advertised through `X-RateLimit-*` response headers.\n\n## Data freshness\nDatasets are aggregated nightly and reflect complete days up to **J-1**\n(yesterday, UTC). The nightly aggregation runs roughly **00:05–06:00 UTC**;\nduring that window the most recent day may still be in motion. Pull J-1 data\n**after 06:00 UTC**, and use `GET /status` `datasets..latest_date` as the\nfreshness signal.\n\n## Tenancy\nEach key carries exactly one brand. Every row is scoped to that brand; a\nmarket / content / user that belongs to another brand (or does not exist) is\na flat `404 not_found`. There is no implicit cross-brand access.\n", "type": "text/plain" } } }