API de Eventos del proyecto

Lista eventos duraderos del proyecto en orden ascendente por secuencia.

La paginación es contigua: pase el next_cursor devuelto como after para continuar exactamente donde la página se detuvo. next_cursor es el cursor del último evento devuelto mientras ya existen eventos más nuevos, y null al final del historial. limit por defecto es 50 y acepta 1-200; un valor fuera de ese rango se rechaza con invalid_request y un miembro errors[] nombrando limit.

No se admite paginación por desplazamiento. source=log lista el registro del Player en su lugar: los informes de condición que envían los Players (runtime.reported) en orden ascendente por hora de recepción, filtrados por screen_id y severidad en una ventana desde hasta (por defecto las últimas 24 horas, máximo 31 días).

Sus cursores son opacos: lg1_ o ev1_ según dónde el servidor guarda el registro del Player, así que devuelva el que una página retornó; un cursor del otro tipo se rechaza con invalid_request nombrando el campo. Los registros del Player no tienen secuencia, no están en GET /stream/project y no se entregan a webhooks.

Un registro se reconoce cuando la cola del log del Player lo acepta y se mantiene para la retención de eventos del proyecto. Una consulta con el último cursor y la ventana predeterminada sigue al log. Los registros del log del Player no están en la lista predeterminada (source=project). from y to se rechazan con invalid_request a menos que source sea log.

La lista de proyectos toma screen_id, playlist_id y application_id para leer los eventos de una pantalla, lista de reproducción o aplicación, todos con alcance al proyecto de la credencial (un id indica qué eventos leer, nunca de quién): screen_id mantiene los eventos cuyo recurso es esa pantalla; playlist_id los eventos cuyo recurso es esa lista de reproducción más los eventos que la nombran como details.playlist_id (una pantalla que la toma); application_id los eventos cuyo recurso es esa aplicación más los que llevan esa aplicación como application_id (sus versiones y entradas clave/valor).

Un valor que no es un id de su tipo se rechaza con invalid_request nombrando el campo; playlist_id y application_id se rechazan con source=log, cuyos registros pertenecen solo a una pantalla.

Ambas fuentes toman resource_id, tipo y severidad (como mínimo), combinados entre sí, con los filtros de id y con paginación; un registro de log de Player es un registro runtime.reported cuyo recurso es su pantalla, por lo que un resource_id que no sea esa pantalla o un tipo que excluya runtime.reported responde con una página vacía. Las páginas before (o order=desc) muestran primero las más nuevas: next_cursor es entonces el cursor del ítem más antiguo devuelto y se pasa de nuevo como before para continuar hacia ítems más antiguos.

Sin from, una página newest-first source=log alcanza más allá de las 24 horas predeterminadas hasta el registro más antiguo que la retención de eventos del proyecto conserva, como máximo 31 días por debajo del límite superior de la página por solicitud. Una página newest-first source=log puede contener menos registros que el límite, incluso ninguno, con un next_cursor; null aún la termina, al final del registro retenido.

Un llamador limitado a pantallas (docs/screen-scope.md) lee un feed filtrado: eventos de pantallas dentro de su alcance, de las carpetas de pantallas que puede ver (las suyas, las que están encima y las que están dentro; screen.moved solo cuando el destino está dentro de su alcance), de campañas, listas de reproducción, medios, aplicaciones y tarjetas, y revisiones playlist_change.

Se omite cualquier otro evento, así que una página puede contener menos eventos que limit, incluso ninguno, con un next_cursor; siga paginando con él. source=log necesita un screen_id dentro de su alcance. No se envían los eventos sobre el propio proyecto.

Flujo de escucha del proyecto reproducible. Los registros del log del reproductor (runtime.reported) se leen con GET /api/events?source=log y no están en este flujo. Abrir esta solicitud cuesta 1 crédito como la suscripción de escucha. Se omiten los encabezados de crédito. Los eventos facturados posteriores cuestan 1 crédito cada uno; screen.*, runtime.*, alert_mute.* y application.event están exentos.

Los latidos y el preámbulo de reintento nunca se cobran. stream.cursor y stream.resync_required se facturan. La idempotencia de débito es sse-event:<project_id>:<sequence>, por lo que la reconexión y repetición es gratuita. Un evento facturado no pagado no se escribe y el stream se cierra.

Una transmisión abierta con una sesión del panel no factura nada (ni la apertura ni sus eventos), igual que las solicitudes API del panel; aun así ocupa una de las plazas de transmisión del proyecto. Un llamador limitado a pantallas (docs/screen-scope.md) recibe el mismo feed filtrado que GET /api/events: no se envía ningún frame por un evento descartado y stream.cursor sigue moviendo la posición.

El alcance se lee cuando se abre la transmisión, y el árbol de carpetas otra vez ante un movimiento o un evento de carpeta; un alcance reducido se aplica a una transmisión abierta cuando se reconecta.