# Métricas

Impresiones, alcance, vistas, me gusta, comentarios, compartidos, guardados, clics y tasa de interacción de cada post, por red; seguidores y promedios por cuenta; y un resumen del espacio. Todo pide el scope `posts:read` ([claves limitadas](https://wyroapi.com/docs/claves)).

## Un 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": "…"
}
```

- Una entrada por cuenta de destino. `null` en una métrica quiere decir que **esa red no la informa** (mira la tabla de abajo); `0` es un cero real.
- `available: false` trae `reason` y un `reason_text` en el idioma del espacio: `not_published` (programado o todavía saliendo), `failed` (la publicación falló ahí), `syncing` (la red todavía no las entregó: vuelve a consultar en unos minutos), `not_available` (esa red o ese post no da métricas), `post_not_found` (se borró en la red), `temporarily_unavailable`.
- `engagement_rate` es un porcentaje: (likes + comments + shares + saves) / (impressions, si no reach, si no views) × 100. `totals` suma las redes.
- `GET /v1/posts/{id}` (y la lista) también trae un `metrics` compacto con los totales cuando los hay, leído solo de la caché.

### Qué tan frescas

Las redes actualizan las métricas cerca de una vez por hora, así que wyro las guarda **1 hora** y responde desde ahí (rápido, y sin gastar los límites de las redes). Pasada esa hora, la siguiente lectura vuelve a consultar. Un post nunca se consulta más de **una vez cada 15 minutos**: `?refresh=true` fuerza una lectura nueva dentro de la hora, con ese límite. `fetched_at` dice cuándo se leyeron los números, `stale: true` que tienen más de una hora (no se pudo consultar la red) y `next_refresh_at` cuándo puede haber una lectura nueva.

## Una cuenta

```
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` y `change_pct` en el rango, y `series` (un punto por día). Las redes actualizan los seguidores una vez por día.
- `posts`: cuántas salieron en el rango y cuántas tienen métricas; `totals` y `averages` (por post) de sus métricas; `best_post` (la de más interacciones).
- `since` / `until`: YYYY-MM-DD (el día entero, hora de Buenos Aires) o ISO 8601. Por defecto, los últimos 30 días; como mucho 366.

## El espacio

`GET https://wyroapi.com/v1/analytics/overview` mantiene todos sus campos y suma `performance`: publicaciones **publicadas** en el rango con métricas, `totals`, `by_platform`, las `top_posts` (5) y una `series` diaria (posts, impressions, reach, views, interactions).

## Qué informa cada red

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

LinkedIn informa clics en páginas de empresa y guardados en perfiles personales. Las historias de Facebook no tienen clics.

## Modo prueba

Con una clave de prueba (o en cuentas simuladas) las métricas son **simuladas**: números realistas que dependen del id del post (el mismo post da siempre los mismos números) y crecen durante el primer o segundo día, con `simulated: true`. No se lee nada de ninguna red. Muéstralas como ejemplo, nunca como resultados reales.

## Partners

Un partner que actúa por un cliente (token de partner + `X-Wyro-External-Id`) lee las métricas de ese cliente, y solo las suyas.

## Desde el agente (MCP)

`wyro_metricas`: sin argumentos, el último post publicado («¿cómo le fue a mi último post?»); con `post_id`, ese post; con `cuenta` (id de la cuenta o red), el resumen de la cuenta (`desde` / `hasta` para el rango). Responde en el idioma del usuario.

## En el panel

El detalle de cada post muestra las métricas por red y cuándo se actualizaron; Inicio tiene un bloque **Rendimiento** del mes (interacciones, impresiones y vistas, tasa de interacción, mejor publicación), y Cuentas muestra los seguidores de cada cuenta.
