Periods
One frozen calendar month or quarter with every metric, its prior value, delta and direction, plus the metric registry that defines each figure.
Why periods
The dashboard headline is a single day's report, and a days window recomputes over a rolling window that answers differently on the 3rd and the 9th. That drift is what puts an inverted arrow in a month-over-month deck. A period is a scoping parameter, not a date filter: period=2026-08 names the row frozen when August closed, and it answers identically however later it is asked.
A closed month is frozen on the 1st and read from the archive. The open month is computed month to date and says so (status: open). A quarter is derived from its three months by a rule per metric: averages weighted by measured days or runs, counts summed, end-of-period figures taken from the last archived month. A recompute that changes a stored figure is recorded as a restatement rather than silently overwriting it. The same resolver serves the API, the MCP server, the Agent and the Reports page, so a number cannot differ between them for the same period.
Endpoint
Returns the whole month or quarter: every single-number metric under metrics with the prior period alongside and the delta and direction already computed, the lists and maps under breakdowns, and the unit and direction of each metric under metric_meta.
Query Parameters
brand_idstringBrand UUID from /get-brands. Required unless brand_ids is given; never both.
brand_idsstringSeveral brands at once: comma-separated UUIDs, up to 12. One compact row per brand per closed month with the prior month's delta; period as YYYY-MM keeps that month and the month before it. Ids that are not among your brands come back in excluded and are never read. Quarters, view, compare and include do not apply.
periodstringA month as YYYY-MM (2026-08) or a quarter as YYYY-Qn (2026-Q3). Defaults to the most recently closed month. A malformed key returns 400.
viewstringsummary, or list: the index of archived months and quarters for the brand
Default: summary
comparebooleanInclude the prior period and the computed deltas
Default: true
includestringComma-separated extras. definitions adds each metric's one-line definition under definitions.
monthsintegerview=list only: how many closed months to index. 1 to 36.
Default: 12
view=summary (default)
Without period the summary is for the most recently closed month. The period block says exactly what was resolved; read status and source before publishing a figure.
Period (also prior)
keystringThe period key, 2026-08 or 2026-Q3
kindstringmonth or quarter
labelstringAugust 2026, Q3 2026
startstringFirst day of the period, YYYY-MM-DD
endstringLast day of the period, inclusive
statusstringclosed, or open for the current month and for a quarter with a month still running
sourcestringarchive (frozen row), computed (open month, or a closed month archived on demand), derived_from_months (quarter), missing (nothing archived yet)
frozen_atstringnullableWhen the row was written. For a quarter, the latest freeze among its months.
pipeline_versionstringnullableThe rollup pipeline that produced the row
restated_atstringnullableWhen a figure was last restated
restatementsarrayEvery restatement: at, note, pipeline_before, pipeline_after, and changed with the old and new value per field
coverageobjectdays_in_period, report_days, perception_runs, citation_days, audit_count and data_status (complete, partial or empty). A quarter adds months_archived and a per-month list.
fields_computedarrayMetric ids computed in this request rather than read from the archive
fields_missingarrayMetric ids with no value for the period
notesarrayPlain-language caveats: an open month, a month computed on demand, a restatement, a plan withholding
monthsobjectnullableQuarters only: each month key with its source
rank_sourcestringnullableHow the month-end rank was produced; recompute means it was rebuilt from the retained raw answers when the month closed
Metric entry (metrics.*)
valuenumbernullableThe metric for the period
priornumbernullableThe same metric for the prior period. Absent when compare=false.
deltanumbernullablevalue minus prior, in the metric's own unit
delta_pctnumbernullablePercentage change against the prior. Left out when the prior is zero, because a change from zero is a tracking artifact.
positions_gainedintegernullableRanks only: prior minus value, so a positive number is an improvement
directionstringnullableup, down or held from the metric's own point of view, so rank 11 to 10 is up. Metrics with no better direction say higher, lower or held.
delta, a positions_gained of 1 and a direction of up. Print the direction word, not the sign of the delta.Breakdowns
Lists and maps live under breakdowns, each with the prior period alongside where it exists.
model_visibility:models[]with visibility, presence, measured days and mentions per model, plusstrongest,weakestandzero_modelstop_competitors:competitors[]with rank, visibility,prior_rank,positions_gained,visibility_deltaandnew_in_list, plusnotable_change, the rival that gained mosttop_prompts: the prompts with the highest average visibility, each flaggednew_entrantagainst the prior periodtag_visibility: average visibility per prompt tag withzero_promptsand the prior valueperception_categories:categorieskeyed by category with score, prior and direction, plusstrongestandweakestperception_competitors: average perception score per tracked competitor, the brand includeddescriptors_end:primary,emergingandfadingdescriptors from the last perception run of the periodcitation_top_pages: the pages naming the brand that were cited most, with citations inside the period and the models that cited themcitation_top_gap_domains: the domains cited most with no page naming the brand, the outreach targets
view=list
The archive index: which closed months exist for the brand, the quarters they form, and the open month. Use it before asking for a period so a missing month is not mistaken for a month with no data.
Status, sources and restatements
status is closed or open. An open month is month to date, is never persisted, carries no month-end rank, and will change until it closes. A quarter with a month still running is open too.
source says where the figures came from. archive is the frozen row. computed is the open month, or a closed month that was not archived yet and has just been computed from retained raw data and stored; it is frozen from then on, and one request fills at most one month. derived_from_months is a quarter. missing means the archive holds nothing for that brand and month and the fill was not possible in this request; every metric is null and notes says so.
A recompute that changes a stored figure appends an entry to restatements with at, note, the pipeline version before and after, and changed keyed by field with the old and new value. The original frozen_at is kept and restated_at marks the latest restatement, so a report can name the change instead of showing a different number with no explanation.
value: null, its breakdown is dropped, and period.notes names the withheld groups.Get Metrics
The metric registry: every figure the period endpoints report, with its label, one-line definition, unit, direction of improvement, how a month is formed from daily readings, and how two periods compare. It takes no brand_id. Product tooltips, the Learn metrics page and the MCP trakkr://metrics resource render from the same source.
Metric
idstringThe key used in metrics and breakdowns, for example visibility_avg
labelstringDisplay label, for example Visibility average
groupstringvisibility, competitors, citations, prompts, perception or site_health
unitstringscore, percent, count, rank, map or list
precisionintegerDecimal places the value is rounded to
betterstringhigher, lower or none
aggregationstringHow the month is formed: mean_daily, sum_daily, sum_activity, mean_runs, end_of_period, last_run, min_daily, max_daily, count_days, count_runs, derived or recompute
comparisonstringpoints, percent, positions or none
kindstringmeasure (one number), breakdown (a list or map) or derived (computed from other archived figures)
definitionstring/get-metrics and include=definitions only: the one-line definition
aggregation_notestring/get-metrics and include=definitions only: the aggregation rule in prose
quarter_rulestring/get-metrics and include=definitions only: weighted_days, weighted_runs, sum, last, min, max, merge_sum or none
learn_urlstringnullable/get-metrics and include=definitions only: the Learn page anchor for the metric, where one exists
The 35 metric ids, in the order a report reads them. Visibility: visibility_avg, presence_avg, mentions_total, position_avg (answer position when mentioned, not competitor rank), visibility_min, visibility_max, report_days, model_visibility. Competitors: rank_end, rank_avg, rank_pool_end, top_competitors. Citations: citations_total, citation_brand_mentions, citation_brand_pages_cumulative_end, citation_days, citation_source_domains_end, citation_source_domains_brand_end, citation_source_domain_share_pct, citation_top_pages, citation_top_gap_domains. Prompts: prompts_measured, prompts_with_visibility, prompt_coverage_pct, top_prompts, tag_visibility. Perception: perception_score_avg, perception_categories, perception_competitors, descriptors_end, perception_runs. Site health: audit_score_end, audit_open_issues_end, audit_count. Traffic: ai_sessions_total, AI-referred sessions from the connected analytics property, read once, three days after the month ends, so the provider has finished counting it.
The definitions in prose are on the Learn metrics page.
period on the other endpoints
Seven read endpoints accept period=YYYY-MM or period=YYYY-Qn and then read their own shape from the archive. When period is set, days is ignored and the response carries the same period block as above. A malformed key returns 400.
/get-scores: every view. Not combinable withtag_idsorprompt_id(400); visibility by tag for the period is in the summary's breakdowns./get-rankings:view=overallonly.win_rateandthreat_countare null, and a month with no archived rank returns 404./get-models:total_queriesis the number of measured days for the model,presenceis filled, and theaverage_positionand top-3 fields are null./get-competitor-data:view=summaryonly, and the response takes a period shape:your_rank,rank_pool,your_visibility,competitors[]withprior_rank,positions_gained,visibility_deltaandnew_in_list,notable_changeandperception_competitors./get-citations:view=top_pagesandview=analytics.appearance_countis the page's citations inside the period, withappearance_count_periodandmodelsalongside. In analytics,top_domainsare the domains cited most with no page naming the brand, andperiod_figurescarries the brand-page figures./get-perception:view=dashboardandview=metrics.perception_score.change_periodis the change against the prior period./get-audits: the audit whose score stood at the end of the period. Site health for the period isaudit_score_endin the summary.
Use Cases
- Build a monthly client report that fetches the same figures again next quarter
- Compare August with July, or Q3 with Q2, with the direction already right for ranks
- Check
status,sourceandrestatementsbefore a number goes into a deck - Render metric labels, units and definitions from
/get-metricsinstead of hard-coding them - List what is archived with
view=listbefore backfilling a warehouse