---
title: "Analytics overview"
method: GET
path: "/analytics/overview"
tags: ["Analytics"]
---

# Analytics overview

`GET /analytics/overview`

## Request

- Base URL: `https://api.rizamo.com/v1`
- URL: `https://api.rizamo.com/v1/analytics/overview`
- Auth: HTTP bearer

The numbers of the team's accounts and of every post on them, made in Rizamo or anywhere else, for a period and the one before it: views, reach, engagements, the engagement rate of the posts published, posts published, followers, the accounts' own reach and accounts engaged, each day, each network, and the top posts. A period of `days` ends yesterday, the last complete day, as `to` does when left out. With `attribution` received (the default), views are each account's own views of each day, as its network counts them (its posts' gains where its days give none, and with `fields`), and reach and engagements what arrived on the posts in the period, on posts of any age, by the day it arrived; with publish, they are the numbers so far of the posts published in the period, by the day each went out. A number a network does not give is missing, never 0, and `notes` says why. Post numbers follow the days of the profile's time zone (pass `timeZone` for another); followers and the accounts' own numbers come by the network's days, matched by date (Meta's run on Pacific time, TikTok's on UTC). TikTok's days come 2 days late and YouTube's 3.

## Query parameters

- `days` integer: The last this many complete days, up to yesterday in `timeZone`: today is not over, so it is left out. 30 when neither this nor `from` is given.
- `from` string, date: Instead of `days`: the first day, such as 2026-10-01.
- `to` string, date: With `from`: the last day, yesterday when left out (today when `from` is today). Up to 365 days in all.
- `profileId` string: Only this profile's (`prof_`): one brand or client, from List profiles. A profile you do not reach is refused as not found.
- `timeZone` string: The time zone the days are in. Left out: the profile's with `profileId`; else the one every profile in reach shares, or UTC when they differ.
- `fields` object: Only posts made in Rizamo whose custom fields have these values, for example `fields[campaign]=Winter menu`: posts made in the networks' own apps have no fields, so they are left out, and so are followers.
- `attribution` 'received' | 'publish': received (the default): what arrived in the period, on posts of any age, on the day it arrived. publish: the posts published in the period, with their numbers so far, on the day each went out.
- `interval` 'day' | 'week' | 'month': How `series` groups the days: day (the default), week (ISO weeks, Monday to Sunday) or month (calendar months). A week's or month's point counts its days as `kpis` counts a period's, from `date` to `to`, and the first and last can hold fewer days. Week or month keeps a long period short.

## Response `200`

OK

- AnalyticsOverview
  - `from` string, date, required: The period's first day, in `timeZone`.
  - `to` string, date, required: Its last day: yesterday, the last complete day in `timeZone`, unless `to` was given.
  - `timeZone` string, required: The time zone the days are in.
  - `attribution` 'received' | 'publish', required: received (the default): what arrived in the period, on posts of any age, on the day it arrived. publish: the posts published in the period, with their numbers so far, on the day each went out.
  - `previous` object, required: The period compared against: as many days, right before.
    - `from` string, date, required
    - `to` string, date, required
  - `kpis` object, required
    - `views` object, required: The main number. received: each account's own views of the period's days, as its network counts them on its own screen (Business Suite, TikTok Studio, YouTube Studio): every post, reel, story or video of any age. An account's days are its network's own (Meta's and YouTube's run on Pacific time, TikTok's on UTC), matched to the period's days by date whatever `timeZone` is. An account whose days give no views (not collected yet, or a network that gives none) counts what its posts gained instead, by the day it arrived; with `fields`, only the posts' views count. A day not in yet (Meta's are read from 10:00 UTC, TikTok's come 2 days late, YouTube's 3) adds nothing, and as many days at the end of the period before are left out of `previous`, so like is compared with like. publish: the views so far of the posts published in it (the period before had longer to gather them). Instagram and Facebook stopped counting impressions in 2025, and views (which count replays) are never impressions.
      - `value` number
      - `previous` number: The same number for the period before. Missing when Rizamo does not have all of it, and `notes` says why: an account connected after it began (what its posts gathered before then is on no day), an account's own days starting later, or posts not known that far back.
    - `reach` object, required: People reached, per post and per network: one person who saw two posts counts twice. received: what the period added to the posts, by the day it arrived; publish: so far, on the posts published in it. The accounts' own reach is `accountMetrics.reach`.
      - `value` number
      - `previous` number: The same number for the period before. Missing when Rizamo does not have all of it, and `notes` says why: an account connected after it began (what its posts gathered before then is on no day), an account's own days starting later, or posts not known that far back.
    - `engagements` object, required: Interactions with the posts, as each network counts them: Instagram, its own total (total_interactions); Facebook, its likes, comments and shares added up (stories: their own total, story_interaction); TikTok, its likes, comments, shares and saves added up; Threads, its likes, comments, reposts, quotes and shares added up; LinkedIn, its likes, comments, reposts, shares and saves added up; YouTube, none. received: those that arrived in the period; publish: those so far on the posts published in it.
      - `value` number
      - `previous` number: The same number for the period before. Missing when Rizamo does not have all of it, and `notes` says why: an account connected after it began (what its posts gathered before then is on no day), an account's own days starting later, or posts not known that far back.
    - `engagementRate` object, required: Engagements per 100 people reached, to two decimals, of the posts published in the period, with their numbers so far, as each post's own rate is reckoned, in both attributions: over the posts whose reach is above 0, on every network alike. Posts with no reach, such as Threads posts, YouTube videos and Facebook reels Meta gave no viewers for, are left out rather than measured against their views, which count replays, and so is a post whose engagements or reach the network hides. Missing when no post of the period has reach; `previous` is the posts published in the period before, with their numbers so far, so they had longer to gather them. It is not capped at 100: engagements can outnumber the people reached.
      - `value` number
      - `previous` number: The same number for the period before. Missing when Rizamo does not have all of it, and `notes` says why: an account connected after it began (what its posts gathered before then is on no day), an account's own days starting later, or posts not known that far back.
    - `posts` object, required: Posts published in the period, made in Rizamo or anywhere else.
      - `value` integer, required
      - `previous` integer: Missing when Rizamo's post history does not reach back that far: it reads each account's posts back 12 months from its connection.
    - `followers` object, required: From each account's own days. Missing, with a note, where they were not collected.
      - `value` integer: Followers on the period's last day, every account added up.
      - `change` integer: Followers gained in the period, net of those lost.
      - `previous` integer: The change in the period before.
  - `accountMetrics` object, required: The accounts' own numbers, added up over the period's days: views, engagements, follows, unfollows, profile_actions (taps on a profile's buttons) and more, as each network gives them, such as Facebook's profile_visits and video_views, Threads' views (its posts' views, which Meta's reference calls profile views), reposts, quotes and clicks (on links the profile shared), or YouTube's watch_time (in milliseconds, as every watch time) and follows and unfollows (subscribers gained and lost), 2 to 3 days late. Views and reach come split too, each part as the network gives it, so the parts need not add up to the whole: by followers (views_followers and views_non_followers on Instagram, Facebook Pages and YouTube, where they are subscribers or not; reach_followers and reach_non_followers on Instagram), by format (views_feed, views_carousel, views_reel and views_story on Instagram; views_short, views_video and views_live on YouTube) and by ads (views_paid on Instagram and Facebook Pages, views_organic on Facebook Pages). Only metrics in each network's reference are read. reach (people who saw the accounts' content: Instagram, Facebook Pages, and TikTok accounts with advanced access) and accounts_engaged (Instagram, and TikTok with advanced access) are each day's people added up, so someone reached on two days counts twice; missing where no account gives them. A day not collected adds nothing, and `notes` says so.
  - `series` object[], required: Every day of the period, or with `interval` week or month every ISO week or calendar month, cut to the period. received: each account's own views of that day; each change between two of Rizamo's reads of a post (engagements, and views where an account's days give none) on the day it arrived, from the day its account was connected, a late network's first numbers (TikTok's, YouTube's) on the day the post went out, even a day before the period (left out of it then, and `notes` says so). publish: each post's numbers so far go on the day it was published. A week's or month's point is the period's totals over its days, as `kpis` and `byNetwork` count them: what arrived over them, a change over several of them included (by day it is in `combined`), followers on its last day, and the accounts' reach and accounts engaged added up. A number none of its days has is missing, never 0.
    - `date` string, date, required: The day. With `interval` week or month, the first day the point covers.
    - `to` string, date: With `interval` week or month: the last day the point covers, so a point is its week or month cut to the period. Missing by day, where a point covers `date` alone.
    - `views` integer: received: the accounts' own views that day (posts' gains for an account whose days give none). publish: the views so far of the posts published that day.
    - `engagements` integer: received: engagements that arrived that day. publish: those so far on the posts published that day.
    - `followers` integer: Followers at the end of the network's day of that date (Meta's and YouTube's run on Pacific time, TikTok's on UTC), every account added up. Missing on a day an account was not collected. YouTube's are its subscribers as Rizamo read them that day (YouTube rounds them), never worked out for days before. A week's or month's: on its last day, as `kpis.followers.value` counts them, each account's latest count up to 7 days before when that day was not collected.
    - `accountReach` integer: People who saw the accounts' content on the network's day of that date, each account's count added up: Instagram, Facebook Pages, and TikTok accounts with advanced access. Missing on a day none of them gives it.
    - `accountsEngaged` integer: Accounts that interacted with the accounts' content on the network's day of that date, added up: Instagram, and TikTok accounts with advanced access. Missing on a day none gives it.
    - `byNetwork` object[]: The day's views and engagements by network, which add up to `views` and `engagements`: every network in reach that gives them, 0 on a day with none, and a network's views missing on a day not in yet. Missing when the day has neither. Each network counts views its own way, so compare a network with itself. TikTok's days come 2 days late and YouTube's 3: their last days fill in later.
      - `network` 'instagram' | 'facebook' | 'threads' | 'linkedin' | 'tiktok' | 'youtube' | 'x' | 'pinterest' | 'google', required
      - `views` integer: That network's part of the day's `views`.
      - `engagements` integer: That network's part of the day's `engagements`.
  - `combined` object[], required: received only (empty with publish): changes of posts Rizamo cannot place on one day (with `interval` week or month, in one week or month), never split, such as a stretch it could not read an account, or a post read every 30 days (YouTube every 28) after its first 90: engagements, and views only of accounts whose own days give none. In the totals and `byNetwork`, not in `series`. One that began before the period is left out, and what a post gathered before its account was connected is on no day.
    - `from` string, date, required
    - `to` string, date, required
    - `views` integer: Views that arrived over these days.
    - `engagements` integer: Engagements that arrived over these days.
  - `byNetwork` object[], required
    - `network` 'instagram' | 'facebook' | 'threads' | 'linkedin' | 'tiktok' | 'youtube' | 'x' | 'pinterest' | 'google', required
    - `views` integer: Views, as in `kpis`.
    - `engagements` integer: Engagements, as in `kpis`.
    - `posts` integer, required: Posts published in the period.
    - `followers` integer: Followers on the period's last day.
    - `accountReach` integer: Its accounts' own reach, each day's added up over the period: someone reached on two days counts twice. Missing where its accounts give none (Threads, YouTube, TikTok without advanced access).
    - `accountsEngaged` integer: Its accounts engaged, each day's added up over the period. Instagram, and TikTok with advanced access; missing elsewhere.
  - `topPosts` PostResult[], required: Up to 10 posts published in the period and still on their network, by their views so far; then posts whose network gives no views, by engagements. Every post of the period: `List how each post did`.
    - `networkPostId` string, required: The post on its network, as `Get a post on a network` returns it.
    - `postId` string, nullable, required: The Rizamo post it went out as. Null when it was made elsewhere.
    - `accountId` string, required
    - `network` 'instagram' | 'facebook' | 'threads' | 'linkedin' | 'tiktok' | 'youtube' | 'x' | 'pinterest' | 'google', required
    - `format` 'feed' | 'carousel' | 'reel' | 'story' | 'video' | 'short' | 'photo' | 'document' | 'pin', required: What a target publishes: feed, carousel, reel, story, video, short, photo, document or pin.
    - `caption` string, nullable, required
    - `url` string, nullable, required
    - `thumbnailUrl` string, nullable, required: A small copy of its picture on Rizamo's media host: the link works for a few hours.
    - `publishedAt` string, date-time, required
    - `deletedAt` string, date-time, nullable, required: When Rizamo found it gone from the network: its numbers are the last read, and it keeps no caption or picture.
    - `metricsAt` string, date-time, nullable, required: When its numbers were read. Null until the first read, an hour after it went out.
    - `views` integer: Its views so far.
    - `reach` integer: People it reached so far.
    - `engagements` integer: Its engagements so far.
    - `engagementRate` number: Engagements per 100 people reached, to two decimals. Missing where the post has no reach, such as a Threads post, a YouTube video or a Facebook reel Meta gave no viewers for, or its reach is 0. It is not capped at 100: a post with more engagements than people reached, as when one person likes, comments and shares, rates above it.
    - `metrics` object, nullable, required: Every number of its latest read, by the names a network post's `metrics` uses: views, reach and engagements again, and the likes, comments, shares, saves, follows, profile_visits, watch times (watch_time and avg_watch_time, in milliseconds) or a story's replies and taps its network gives. A null value is one the network hides. Null until the first read.
    - `masked` string[], required: Its numbers the network hides because they are small (Meta: under 5): they count as nothing.
    - `metricsUnavailable` string, nullable, required: Why it has no numbers and will get none, as `Get a post on a network` says it: a Facebook story that ended before Rizamo read it, or a post deleted with no numbers kept. Null otherwise.
    - `details` PostDetails, nullable: What the network says about the post that is not a count: rates in percent, where its views came from, who watched and for how long. The latest read only, with no history (`metrics` has the counts and the timeline their days); each part is the last one a read brought, read when `detailsAt` says. Null until a read brings one, and on networks that give none.
      - `skip_rate` number: The share of views skipped in the first 3 seconds, in percent. From Instagram reels.
      - `completion_rate` number: The share of viewers who watched the whole video, in percent. From TikTok videos.
      - `avg_view_percentage` number: How much of the video a view watched on average, in percent. From YouTube posts.
      - `traffic_sources` object[]: Where its views came from, as the network gives it: each source's share of the views in percent (`percent`), or its views (`views`), never one worked out from the other. From TikTok posts and YouTube posts. Largest first.
        - `source` string, required: Where the views came from: `for_you`, `following`, `profile`, `search`, `sound`, `hashtag`, `direct_message`, `other`, or the network's own name in lower case with underscores.
        - `percent` number: Its share of the views, in percent, where the network gives shares.
        - `views` integer: Its views, where the network gives counts. Never worked out from a share, or a share from them.
      - `viewer_types` object[]: New and returning viewers, followers and non-followers: each type's share of the viewers in percent (`percent`), or its views (`views`), as the network gives it. From TikTok posts.
        - `type` 'new' | 'returning' | 'followers' | 'non_followers', required: new and returning viewers make one split, followers and non_followers another: each adds up to the whole on its own.
        - `percent` number: Its share of the views, in percent, where the network gives shares.
        - `views` integer: Its views, where the network gives counts. Never worked out from a share, or a share from them.
      - `retention` object: How many viewers were still watching at each point of the video, in percent of those who started: by the second (`unit` second) or by the share of the video's length from 0 to 1 (`unit` fraction; YouTube's first point is at 0.01, its last at 1, Facebook's first at 0, where the reel starts). From Facebook reels, TikTok videos and YouTube posts.
        - `unit` 'second' | 'fraction', required: second: `at` is seconds into the video. fraction: `at` is the share of its length, from 0 to 1.
        - `points` object[], required: In order of `at`, at most 100: a longer curve (TikTok's, one a second) is picked down to that many of the network's own points, evenly along it, the first and last kept.
          - `at` number, required
          - `percent` number, required: Viewers still watching, in percent of those who started.
      - `viewer_demographics` AudienceBreakdowns: Who watched it, by age, gender, country and city: the groups the network gives, largest first, each as a share in percent (`percent`, its `count` 0) or as views (`count`), as the network gives it, never one worked out from the other. From Facebook reels and TikTok posts. A part the network does not give is empty (TikTok gives no ages per video, Facebook no cities).
        - `age` AudienceShare[], required
          - `value` string, required: The group: an age range (25-34), a gender (female, male, unknown), a country code (PT), a city (Lisbon, Lisbon District) or, on LinkedIn, a market area (Greater Lisbon), an industry, a job function, a seniority or a company size (2-10 employees), as LinkedIn names them.
          - `count` integer, required: People in the group; views where the network counts views (YouTube's countries, a Facebook reel's viewers). 0 where the network gives only a share (`percent`).
          - `percent` number: The group's share in percent, where the network gives shares and no counts: YouTube's viewers by age and gender, of the views of signed-in viewers.
        - `gender` AudienceShare[], required
          - `value` string, required: The group: an age range (25-34), a gender (female, male, unknown), a country code (PT), a city (Lisbon, Lisbon District) or, on LinkedIn, a market area (Greater Lisbon), an industry, a job function, a seniority or a company size (2-10 employees), as LinkedIn names them.
          - `count` integer, required: People in the group; views where the network counts views (YouTube's countries, a Facebook reel's viewers). 0 where the network gives only a share (`percent`).
          - `percent` number: The group's share in percent, where the network gives shares and no counts: YouTube's viewers by age and gender, of the views of signed-in viewers.
        - `country` AudienceShare[], required: The top 45, as the network gives them (LinkedIn its top 100).
          - `value` string, required: The group: an age range (25-34), a gender (female, male, unknown), a country code (PT), a city (Lisbon, Lisbon District) or, on LinkedIn, a market area (Greater Lisbon), an industry, a job function, a seniority or a company size (2-10 employees), as LinkedIn names them.
          - `count` integer, required: People in the group; views where the network counts views (YouTube's countries, a Facebook reel's viewers). 0 where the network gives only a share (`percent`).
          - `percent` number: The group's share in percent, where the network gives shares and no counts: YouTube's viewers by age and gender, of the views of signed-in viewers.
        - `city` AudienceShare[], required: The top 45, as the network gives them; on LinkedIn, its market areas, its top 100.
          - `value` string, required: The group: an age range (25-34), a gender (female, male, unknown), a country code (PT), a city (Lisbon, Lisbon District) or, on LinkedIn, a market area (Greater Lisbon), an industry, a job function, a seniority or a company size (2-10 employees), as LinkedIn names them.
          - `count` integer, required: People in the group; views where the network counts views (YouTube's countries, a Facebook reel's viewers). 0 where the network gives only a share (`percent`).
          - `percent` number: The group's share in percent, where the network gives shares and no counts: YouTube's viewers by age and gender, of the views of signed-in viewers.
        - `industry` AudienceShare[]: LinkedIn only: a Page's followers by industry, its top 100.
          - `value` string, required: The group: an age range (25-34), a gender (female, male, unknown), a country code (PT), a city (Lisbon, Lisbon District) or, on LinkedIn, a market area (Greater Lisbon), an industry, a job function, a seniority or a company size (2-10 employees), as LinkedIn names them.
          - `count` integer, required: People in the group; views where the network counts views (YouTube's countries, a Facebook reel's viewers). 0 where the network gives only a share (`percent`).
          - `percent` number: The group's share in percent, where the network gives shares and no counts: YouTube's viewers by age and gender, of the views of signed-in viewers.
        - `jobFunction` AudienceShare[]: LinkedIn only: a Page's followers by job function.
          - `value` string, required: The group: an age range (25-34), a gender (female, male, unknown), a country code (PT), a city (Lisbon, Lisbon District) or, on LinkedIn, a market area (Greater Lisbon), an industry, a job function, a seniority or a company size (2-10 employees), as LinkedIn names them.
          - `count` integer, required: People in the group; views where the network counts views (YouTube's countries, a Facebook reel's viewers). 0 where the network gives only a share (`percent`).
          - `percent` number: The group's share in percent, where the network gives shares and no counts: YouTube's viewers by age and gender, of the views of signed-in viewers.
        - `seniority` AudienceShare[]: LinkedIn only: a Page's followers by seniority.
          - `value` string, required: The group: an age range (25-34), a gender (female, male, unknown), a country code (PT), a city (Lisbon, Lisbon District) or, on LinkedIn, a market area (Greater Lisbon), an industry, a job function, a seniority or a company size (2-10 employees), as LinkedIn names them.
          - `count` integer, required: People in the group; views where the network counts views (YouTube's countries, a Facebook reel's viewers). 0 where the network gives only a share (`percent`).
          - `percent` number: The group's share in percent, where the network gives shares and no counts: YouTube's viewers by age and gender, of the views of signed-in viewers.
        - `companySize` AudienceShare[]: LinkedIn only: a Page's followers by the size of the company they work at.
          - `value` string, required: The group: an age range (25-34), a gender (female, male, unknown), a country code (PT), a city (Lisbon, Lisbon District) or, on LinkedIn, a market area (Greater Lisbon), an industry, a job function, a seniority or a company size (2-10 employees), as LinkedIn names them.
          - `count` integer, required: People in the group; views where the network counts views (YouTube's countries, a Facebook reel's viewers). 0 where the network gives only a share (`percent`).
          - `percent` number: The group's share in percent, where the network gives shares and no counts: YouTube's viewers by age and gender, of the views of signed-in viewers.
    - `detailsAt` DetailsAt, nullable: When each of `details` was read, by its key. A read that does not bring a detail (TikTok stops giving them after a week with no views) leaves its last value and time, so a detail read before `metricsAt` is from an earlier read than the numbers. Null when `details` is.
  - `notes` AnalyticsNote[], required: Why a number is missing or partial, such as a Facebook Page read without insights, or an account that needs a new login.
    - `accountId` string, nullable, required: The account it is about. Null when it is about every account.
    - `metric` string, nullable, required: The number it is about, such as views or followers. Null when it is about all of them.
    - `reason` string, required

## Other responses

- `400`: `invalid_request`: A field is missing or wrong, or the request cannot be done as asked: the message names the field or says what to change.
- `401`: `unauthorized`: No API key or sign-in, or the key does not work: it was deleted, or it expired.
- `403`: `forbidden`: The caller may not do this: the key or agent lacks the scope (the message names it), or the action needs another role or a fresh sign-in.
- `404`: `not_found`: No such object, or it is outside your team or the profiles your key reaches.
- `429`: `rate_limited`: Over one of Rizamo's limits, or a network asked Rizamo to slow down: wait for `Retry-After` seconds, or as long as the message says.
- `500`: `internal`: Our side failed: retry, and send the `requestId` if it keeps failing.
- `503`: `timeout`: The request took too long to work out, most often a report: try again in a moment, or ask a report for a shorter period or one profile.

---

[API](https://skmtc.dev/rizamo/apis/rizamo-api.md) - [All operations](https://skmtc.dev/rizamo/apis/rizamo-api/llms.txt) - [OpenAPI document](https://skmtc.dev/rizamo/apis/rizamo-api/revisions/31b0c1b1ffb5?raw)
