stats_fetch
Views/starts/submissions of one entity - "namespace" plus "entityId" says which (a project, a user, or a Riddle by UUID), "view" how deeply. "totals": one aggregate for the period. The response IS the entity's stats document: metrics sit in "core_metrics" under "global_stats" (a Riddle) or under "stats" (a user/project aggregate, or an old Riddle) - read only "stats" and a Riddle with real traffic looks unmeasured. A Riddle also carries one "block__stats" per block, keyed by riddle_get's ids. "timeseries": those numbers per consecutive interval - {intervalDays, intervalCount, intervals}, each {from, to, days, stats} inclusive of both ends. Up to 31 days give one interval per day; a longer range is grouped into at most 31 equal intervals whose "stats" is the interval TOTAL, not a daily number - divide by "days", and never read the shorter final interval as a drop. "breakdown" is per namespace: "riddle" gives one Riddle down to its blocks, choices and fields, every "id" being the stored block id riddle_get's "build" exposes, so a weak question can be fixed directly; "project" gives that tree for every Riddle in it - prefer a short range, or one Riddle, on a big project; "user" gives NOT a deep breakdown but the account-wide summary: one row per Riddle plus the totals over every Riddle in scope, ranked by sortBy, 25 per page ("hasMore" says whether another follows), narrowed with projectIds rather than paged on a big account, requires a USER API key, takes no entityId. Two kinds of "no data": an empty response ({}, always an object, never a list) means nothing was recorded - report "no stats recorded", never 0 - while a missing key inside a POPULATED "core_metrics" is a genuine zero (no "finish" beside a "view" means no submissions). A "breakdown" signals nothing by shape: a Riddle nobody opened still answers with its full tree at 0, so confirm it was published then (riddle_get's "published": null means it never was) before reading zeros as a finding.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number of the account-wide summary, 1-indexed (default: 1). Zero or negative is rejected with a VALIDATION_ERROR, not clamped to page 1 - the same contract as riddle_list/project_list. That view only. | |
| view | Yes | How deeply to measure: "totals" (one aggregate for the period), "timeseries" (that aggregate per consecutive interval, requires dateFrom and dateTo), "breakdown" (the per-block detail, or the per-Riddle summary for namespace "user") or "lookerLink" (no dates, Enterprise): no numbers but {url}, a Looker Studio link opening a ready-made report - per Riddle, per project, or for the whole account (namespace "user", no entityId; with the key\'s own user id: its personal project). On first use the user authorizes the Riddle connector there, then opens the link again. | |
| dateTo | No | End date (inclusive), format: YYYY-MM-DD, e.g. "2026-01-31". Same rules as dateFrom; where a default applies it is today. | |
| sortBy | No | Metric the account-wide summary's Riddles are ranked by before the page is cut: "views" (default), "starts", "submissions" or "timeActive". Sorting always spans the whole account (or the projects given), so page 1 is genuinely the top of the account. That view only. | |
| dateFrom | No | Start date (inclusive), format: YYYY-MM-DD, e.g. "2026-01-01". Required for "timeseries". On "totals" and a Riddle/project "breakdown", omit both dates for alltime and pass only one for an open-ended range; the account-wide summary and the project breakdown instead default to one CALENDAR month before today - the same default the Creator's dashboards use, so 29 to 32 days depending on the month, not exactly 30. Send it explicitly when the exact span matters. | |
| entityId | No | ID of the entity: a project ID (integer as string) for "project", a user ID (integer as string) for "user", a Riddle UUID for "riddle". Get them from project_list, whoami ("user", not the string "user") and riddle_list respectively. Required for every view except the account-wide summary (view "breakdown" with namespace "user"), which measures the API key's own account and rejects it. | |
| namespace | Yes | Entity type to fetch stats for. | |
| projectIds | No | Narrow the account-wide summary to these project IDs (array of integers, from project_list). Omit to cover the whole account, including the personal project. Passing a project the user cannot view stats of is an error, not a silently skipped project. That view only. |