---
title: "List how each post did"
method: GET
path: "/analytics/posts"
tags: ["Analytics"]
---

# List how each post did

`GET /analytics/posts`

## Request

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

Every post published in the period on the team's accounts, made in Rizamo or anywhere else, deleted ones included, with its numbers so far: its lifetime totals as Rizamo last read them, every one its network gives in `metrics`, and its `details` (rates, traffic sources, viewer types, retention, viewers) where its network gives them. Sorted by views unless asked otherwise, a page at a time. Days are the profile's, and a period of `days` ends yesterday, as in Analytics overview.

## 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.
- `sort` 'views' | 'reach' | 'engagements' | 'engagementRate' | 'publishedAt': What to sort by. Posts without that number (a network that does not give it, one it hides, one not read yet) come last.
- `order` 'desc' | 'asc': desc (the default): the highest first. asc: the lowest first.
- `limit` integer: How many to return, up to 100: 25 when left out.
- `offset` integer: How many to skip: the next page starts at `offset` plus `limit`.

## Response `200`

OK

- object
  - `from` string, date, required
  - `to` string, date, required
  - `timeZone` string, required: The time zone the days are in.
  - `total` integer, required: How many posts the period has in all.
  - `items` PostResult[], required
    - `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.

## 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)
