> For the complete documentation index, see [llms.txt](https://docs.videsk.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.videsk.io/es-developers/vpaas/telemetria.md).

# Telemetría

Obtén el análisis de calidad WebRTC de una sala (sesión) bajo demanda: un reporte determinístico con puntajes y recomendaciones, un *snapshot* en vivo, o el resumen persistido de la sesión.

### Autorización

Todos los endpoints descritos a continuación utilizan la cabecera `Authorization` con esquema Bearer.

Un API token lo puedes obtener desde nuestro dashboard. Este deberá ser de tipo `api-token`, el cual es el único permitido para VPaaS.

{% hint style="info" %}
Si estás en ambiente de desarrollo, te recomendamos crear un token sin lista blanca de IPs; esto evitará problemas de bloqueos por IP dinámica.
{% endhint %}

***

### Vistas disponibles (`view`)

| `report` *(default)* | Análisis completo de la sesión: puntaje de calidad, métricas clave, patrones detectados y recomendaciones accionables.         | Cacheado    |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------ | ----------- |
| `snapshot`           | Rollup calculado en tiempo real desde la telemetría cruda. Útil mientras la sesión sigue activa ("qué ha pasado hasta ahora"). | No persiste |
| `summary`            | Rollup persistido de la sesión (por peer y por minuto). Disponible una vez que la sesión fue compilada.                        | Persistido  |

***

## Get session stats

> Retrieve on-demand WebRTC quality analytics for a room (session). Use the view query parameter to choose the analysis type, and the Accept header to choose the response format (text/markdown is only supported for view=report).

```json
{"openapi":"3.0.3","info":{"title":"VPaaS Rooms API","version":"1.0.0"},"servers":[{"url":"https://api.videsk.io","description":"Production server"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Bearer token authentication using API token"}},"schemas":{"StatsReport":{"type":"object","description":"Deterministic per-session analysis (view=report).","properties":{"schemaVersion":{"type":"integer","enum":[1]},"generatedAt":{"type":"string","format":"date-time"},"sessionId":{"type":"string"},"overview":{"type":"object","nullable":true,"properties":{"sessionStart":{"type":"string","format":"date-time"},"sessionEnd":{"type":"string","format":"date-time"},"durationMinutes":{"type":"number"},"totalPeers":{"type":"integer"},"totalRecords":{"type":"integer"}}},"summary":{"type":"object","properties":{"status":{"type":"string","enum":["SUCCESSFUL","DEGRADED","FAILED"]},"score":{"type":"number","description":"Overall quality score 0-100"},"scoreBreakdown":{"type":"object","properties":{"connectionStability":{"type":"number"},"packetLoss":{"type":"number"},"latency":{"type":"number"},"videoQuality":{"type":"number"}}},"keyMetrics":{"type":"object","properties":{"audioLossPct":{"type":"number"},"videoLossPct":{"type":"number"},"avgRttMs":{"type":"number"},"maxRttMs":{"type":"number"},"rttQuality":{"type":"string","enum":["excellent","good","fair","poor"]},"realDisconnections":{"type":"integer"},"reconnections":{"type":"integer"},"connectionTypeChanges":{"type":"integer"},"avgUptimePct":{"type":"number"}}}}},"peers":{"type":"array","items":{"$ref":"#/components/schemas/StatsReportPeer"}},"rtt":{"type":"array","description":"Per-peer round-trip-time aggregates.","items":{"$ref":"#/components/schemas/StatsRtt"}},"packetLoss":{"type":"array","description":"Peers with packet loss greater than zero.","items":{"$ref":"#/components/schemas/StatsPacketLoss"}},"videoIssues":{"type":"array","description":"Peers with freezes or dropped frames.","items":{"$ref":"#/components/schemas/StatsVideoIssue"}},"jitter":{"type":"array","description":"Peers with high jitter.","items":{"$ref":"#/components/schemas/StatsJitter"}},"disconnections":{"type":"array","description":"Telemetry gaps treated as real disconnections.","items":{"$ref":"#/components/schemas/StatsDisconnection"}},"stability":{"type":"array","items":{"$ref":"#/components/schemas/StatsStability"}},"userAgents":{"type":"array","items":{"$ref":"#/components/schemas/StatsUserAgent"}},"patterns":{"type":"array","description":"Detected behavioural patterns with a human-readable verdict.","items":{"$ref":"#/components/schemas/StatsPattern"}},"recommendations":{"type":"object","properties":{"status":{"type":"string","enum":["SUCCESSFUL","DEGRADED","FAILED"]},"items":{"type":"array","items":{"$ref":"#/components/schemas/StatsRecommendation"}}}}},"required":["schemaVersion","generatedAt","sessionId","summary","peers","recommendations"]},"StatsReportPeer":{"type":"object","properties":{"peerId":{"type":"string"},"alias":{"type":"string","nullable":true},"type":{"type":"string","nullable":true},"userAgent":{"type":"string","nullable":true},"connectionType":{"type":"string","nullable":true,"description":"e.g. host, relay"},"protocol":{"type":"string","nullable":true},"networkType":{"type":"string","nullable":true},"country":{"type":"string","nullable":true},"region":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"firstSeen":{"type":"string","format":"date-time","nullable":true},"lastSeen":{"type":"string","format":"date-time","nullable":true},"durationSeconds":{"type":"integer"},"audioLossPct":{"type":"number"},"videoLossPct":{"type":"number"},"videoFreezes":{"type":"integer"},"videoFreezeDuration":{"type":"integer"}}},"StatsRtt":{"type":"object","properties":{"peerId":{"type":"string"},"samples":{"type":"integer"},"avgRttMs":{"type":"number"},"minRttMs":{"type":"number"},"maxRttMs":{"type":"number"},"stddevRttMs":{"type":"number"},"spikeCount":{"type":"integer"}}},"StatsPacketLoss":{"type":"object","properties":{"peerId":{"type":"string"},"audioLossPct":{"type":"number"},"videoLossPct":{"type":"number"}}},"StatsVideoIssue":{"type":"object","properties":{"peerId":{"type":"string"},"videoFreezes":{"type":"integer"},"videoFreezeDuration":{"type":"integer"},"framesDroppedPct":{"type":"number"}}},"StatsJitter":{"type":"object","properties":{"peerId":{"type":"string"},"avgAudioJitterMs":{"type":"number"},"maxAudioJitterMs":{"type":"number"},"avgVideoJitterMs":{"type":"number"},"maxVideoJitterMs":{"type":"number"}}},"StatsDisconnection":{"type":"object","properties":{"peerId":{"type":"string"},"disconnectionTime":{"type":"string","format":"date-time"},"reconnectionTime":{"type":"string","format":"date-time"},"offlineDurationSeconds":{"type":"number"}}},"StatsStability":{"type":"object","properties":{"peerId":{"type":"string"},"sessionDurationMinutes":{"type":"number"},"disconnectionCount":{"type":"integer"},"totalOfflineMinutes":{"type":"number"},"uptimePercentage":{"type":"number"}}},"StatsUserAgent":{"type":"object","properties":{"browser":{"type":"string"},"browserVersion":{"type":"string"},"os":{"type":"string"},"isMobile":{"type":"boolean"},"peerCount":{"type":"integer"},"percentage":{"type":"number"}}},"StatsPattern":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"verdict":{"type":"string"},"severity":{"type":"string","enum":["INFORMATIONAL","LOW","MEDIUM","HIGH","CRITICAL"]},"explanation":{"type":"string"}}},"StatsRecommendation":{"type":"object","properties":{"audience":{"type":"string","enum":["immediate","application","network","client"]},"priority":{"type":"string","enum":["critical","high","medium","low","info"]},"title":{"type":"string"},"detail":{"type":"string"}}},"StatsSnapshot":{"type":"object","description":"Runtime rollup (view=snapshot; never persisted).","properties":{"sessionId":{"type":"string"},"persisted":{"type":"boolean","enum":[false]},"generatedAt":{"type":"string","format":"date-time"},"peers":{"type":"array","items":{"$ref":"#/components/schemas/StatsRollupPeer"}},"timeline":{"type":"array","items":{"$ref":"#/components/schemas/StatsRollupTimelinePoint"}}}},"StatsRollupPeer":{"type":"object","description":"Per-peer rollup row (snake_case; returned by snapshot/summary).","properties":{"session_id":{"type":"string"},"peer_id":{"type":"string"},"first_seen":{"type":"string","format":"date-time","nullable":true},"session_end":{"type":"string","format":"date-time","nullable":true},"duration_seconds":{"type":"number"},"total_samples":{"type":"integer"},"connection_type":{"type":"string","nullable":true},"avg_rtt_ms":{"type":"number","nullable":true},"max_rtt_ms":{"type":"number","nullable":true},"audio_loss_pct":{"type":"number"},"video_loss_pct":{"type":"number"},"video_freezes":{"type":"number","nullable":true},"uptime_pct":{"type":"number"},"country":{"type":"string","nullable":true},"region":{"type":"string","nullable":true}}},"StatsRollupTimelinePoint":{"type":"object","description":"Per-peer, per-minute downsampled point (snake_case).","properties":{"session_id":{"type":"string"},"peer_id":{"type":"string"},"bucket":{"type":"string","format":"date-time"},"samples":{"type":"integer"},"avg_rtt_ms":{"type":"number","nullable":true},"max_rtt_ms":{"type":"number","nullable":true},"avg_audio_jitter_ms":{"type":"number","nullable":true},"avg_video_jitter_ms":{"type":"number","nullable":true},"avg_available_mbps":{"type":"number","nullable":true},"connection_type":{"type":"string","nullable":true},"state":{"type":"string","nullable":true}}},"StatsSummary":{"type":"object","description":"Persisted rollup (view=summary).","properties":{"sessionId":{"type":"string"},"persisted":{"type":"boolean","enum":[true]},"peers":{"type":"array","items":{"$ref":"#/components/schemas/StatsRollupPeer"}},"timeline":{"type":"array","items":{"$ref":"#/components/schemas/StatsRollupTimelinePoint"}}}},"Error":{"type":"object","properties":{"name":{"type":"string","description":"Error type name"},"message":{"type":"string","description":"Error message"},"code":{"type":"integer","description":"HTTP status code"},"className":{"type":"string","description":"Error class name"},"data":{"type":"object","description":"Additional error data"},"errors":{"type":"object","description":"Validation errors (if applicable)"}},"required":["name","message","code"]}}},"paths":{"/vpaas/rooms/{roomId}/stats":{"get":{"summary":"Get session stats","description":"Retrieve on-demand WebRTC quality analytics for a room (session). Use the view query parameter to choose the analysis type, and the Accept header to choose the response format (text/markdown is only supported for view=report).","tags":["Stats"],"parameters":[{"name":"roomId","in":"path","required":true,"description":"Room ID (ObjectId) or external ID","schema":{"type":"string"}},{"name":"view","in":"query","required":false,"description":"Analysis type to return.","schema":{"type":"string","enum":["report","snapshot","summary"],"default":"report"}},{"name":"refresh","in":"query","required":false,"description":"For view=report only. Force regeneration instead of returning the cached report.","schema":{"type":"boolean","default":false}},{"name":"Accept","in":"header","required":false,"description":"Response format. text/markdown is only supported for view=report.","schema":{"type":"string","enum":["application/json","text/markdown"],"default":"application/json"}}],"responses":{"200":{"description":"Successful response. Body shape depends on the view parameter.","headers":{"X-Report-Cached":{"description":"For view=report, \"true\" if the cached report was served, \"false\" if freshly generated.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/StatsReport"},{"$ref":"#/components/schemas/StatsSnapshot"},{"$ref":"#/components/schemas/StatsSummary"}]}},"text/markdown":{"schema":{"type":"string","description":"Rendered Markdown report (view=report only)."}}}},"400":{"description":"Bad request - invalid view","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized - Invalid or missing API token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden - the token is not an api-token, or IP not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found - room not found, or no telemetry available for this session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.videsk.io/es-developers/vpaas/telemetria.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.