# Metrics

Impressions, reach, views, likes, comments, shares, saves, clicks and engagement rate of every post, per network; followers and averages per account; and a summary of the workspace. Everything needs the `posts:read` scope ([limited keys](https://wyroapi.com/en/docs/api-keys)).

## One post

```
curl https://wyroapi.com/v1/posts/post_abc123/metrics -H "Authorization: Bearer $WYRO_API_KEY"
```

```json
{
  "post_id": "post_abc123",
  "status": "published",
  "simulated": false,
  "totals": { "impressions": 15420, "reach": 12350, "views": 900, "likes": 342, "comments": 28, "shares": 45, "saves": 12, "clicks": 189, "engagement_rate": 2.76 },
  "targets": [
    {
      "account_id": "acc_ig1",
      "platform": "instagram",
      "available": true,
      "metrics": { "impressions": 15420, "reach": 12350, "views": 900, "likes": 342, "comments": 28, "shares": 45, "saves": 12, "clicks": null, "engagement_rate": 2.78 },
      "published_url": "https://www.instagram.com/p/…",
      "fetched_at": "2026-11-18T12:00:00.000Z"
    },
    {
      "account_id": "acc_tt1",
      "platform": "tiktok",
      "available": false,
      "reason": "syncing",
      "reason_text": "…",
      "metrics": null
    }
  ],
  "fetched_at": "2026-11-18T12:00:00.000Z",
  "stale": false,
  "next_refresh_at": "2026-11-18T13:00:00.000Z",
  "next_step": "…"
}
```

- One entry per target account. `null` in a metric means **that network does not report it** (see the table below); `0` is a real zero.
- `available: false` comes with `reason` and a `reason_text` in the workspace's language: `not_published` (scheduled or still going out), `failed` (publishing failed there), `syncing` (the network has not delivered them yet: check again in a few minutes), `not_available` (that network or post gives no metrics), `post_not_found` (deleted on the network), `temporarily_unavailable`.
- `engagement_rate` is a percentage: (likes + comments + shares + saves) / (impressions, else reach, else views) × 100. `totals` adds up the networks.
- `GET /v1/posts/{id}` (and the list) also carries a compact `metrics` with the totals when there are some, read only from the cache.

### How fresh

Networks update metrics about once an hour, so wyro keeps them for **1 hour** and answers from there (fast, and it never burns the networks' limits). After that hour the next read asks again. A post is never asked more than **once every 15 minutes**: `?refresh=true` forces a new read within the hour, with that limit. `fetched_at` says when the numbers were read, `stale: true` that they are older than an hour (the network could not be asked), and `next_refresh_at` when the next read can happen.

## One account

```
curl "https://wyroapi.com/v1/accounts/acc_abc123/metrics?since=2026-11-01&until=2026-11-30" -H "Authorization: Bearer $WYRO_API_KEY"
```

- `followers`: `current`, `change` and `change_pct` in the range, and `series` (one point per day). Networks update followers once a day.
- `posts`: how many went out in the range and how many have metrics; `totals` and `averages` (per post) of their metrics; `best_post` (the one with the most interactions).
- `since` / `until`: YYYY-MM-DD (a whole day, Buenos Aires time) or ISO 8601. Default: the last 30 days; at most 366.

## The workspace

`GET https://wyroapi.com/v1/analytics/overview` keeps every field it had and adds `performance`: posts **published** in the range with metrics, `totals`, `by_platform`, the `top_posts` (5) and a daily `series` (posts, impressions, reach, views, interactions).

## What each network reports

| Network | `impressions` | `reach` | `views` | `likes` | `comments` | `shares` | `saves` | `clicks` |
| --- | :-: | :-: | :-: | :-: | :-: | :-: | :-: | :-: |
| Instagram | yes | yes | yes | yes | yes | yes | yes | — |
| Facebook | yes | — | yes | yes | yes | yes | — | yes |
| TikTok | — | — | yes | yes | yes | yes | — | — |
| LinkedIn | yes | yes | — | yes | yes | yes | yes | yes |
| X | yes | — | yes | yes | yes | yes | yes | yes |
| Threads | — | — | yes | yes | yes | yes | — | — |
| YouTube | — | — | yes | yes | yes | — | — | — |
| Pinterest | yes | — | — | — | — | — | yes | yes |

LinkedIn reports clicks on company pages and saves on personal profiles. Facebook stories have no clicks.

## Test mode

With a test key (or on simulated accounts) the metrics are **simulated**: realistic numbers that depend on the post id (the same post always gives the same numbers) and grow during the first day or two, with `simulated: true`. Nothing is read from any network. Show them as an example, never as real results.

## Partners

A partner acting for a client (partner token + `X-Wyro-External-Id`) reads that client's metrics, and only theirs.

## From the agent (MCP)

`wyro_metricas`: without arguments, the latest published post ("how did my last post do?"); with `post_id`, that post; with `cuenta` (account id or network), the account summary (`desde` / `hasta` for the range). It answers in the user's language.

## In the panel

The detail of each post shows the metrics per network and when they were updated; Home has a **Performance** block for the month (interactions, impressions and views, engagement rate, best post), and Accounts shows the followers of each account.
