# Registro de actividad

Lee el registro de tu organización con las llamadas a la API y los eventos de archivos y registros.

URL base: `https://data.inovacc.dev`

## Descripción general

El Registro de actividad es el registro propio de tu organización de lo que ocurrió en Inovacc: cada llamada a la API, y cada evento de archivo y de registro que esas llamadas causaron. Lo lees con un solo endpoint, `GET /v1/activity` en `https://data.inovacc.dev`, filtrado por tiempo, tipo de evento o hash de archivo.

El problema que resuelve es responder "quién hizo qué, y cuándo" sin construir tu propia pista de auditoría. Inovacc mantiene el registro de toda llamada a las API de Datos, de IA y de Eventos, sin importar si tu aplicación se acuerda de escribir algo. El registro es un hecho del servicio, no una opción, y una organización solo ve sus propios registros.

Úsalo para auditorías, para investigar una integración fallida ("¿qué llamadas se rechazaron esta mañana, y con qué código?"), para demostrar que un archivo fue entregado (el evento de descarga lleva el SHA-256 del archivo), y para una vista del tráfico por clave. Para ver cuánto **costó** tu uso de IA, usa el resumen de uso del [Chat con IA](/es/products/ai.chat/) (`GET /v1/usage/summary`): el Registro de actividad registra eventos, nunca precios.

## Conceptos

**Eventos y tipos.** Cada registro es un evento con un `kind`:

| Tipo | Se escribe cuando |
|---|---|
| `api.call` | cualquier llamada autenticada, incluidas las rechazadas (`403`, `429`) |
| `record.write`, `record.delete` | se crea, cambia o elimina un registro (uno por operación de un lote) |
| `blob.write`, `blob.read`, `blob.delete` | se carga, descarga o elimina un blob de una base de datos |
| `file.upload.completed`, `file.download`, `file.delete` | se escribe, descarga o elimina un archivo |
| `file.upload.started`, `file.processed` | los escriben otros servicios de Inovacc, como las cargas y conversiones de IA |

**Qué contiene un registro.** La hora (`at_ms`, milisegundos Unix), la organización, quién actuó (`actor_kind`: `user`, `key` o `service`, y `actor_id`), el servicio de origen `source`, el `method`, la `route` (una plantilla como `/v1/databases/{database}/collections/{collection}/records/{record_id}`, nunca los ids en sí), el `status`, el `outcome`, el `error_code` de un fallo, la latencia, los tamaños de entrada y salida, y para un archivo su tamaño, tipo y SHA-256. `related` apunta a la base de datos, la colección y el registro, o a la carga o el trabajo, de que se trate. Todas las claves están siempre presentes, con `null` cuando no aplican.

**Lo que nunca contiene.** Un prompt, el cuerpo de una respuesta ni el contenido de un archivo. Las llamadas de IA nunca registran el nombre de un archivo.

**País.** Un registro `api.call` lleva `country`: el país de quien llama tal como lo ve el borde de red de Inovacc (dos letras, `XX` cuando se desconoce). Quien llama no puede establecerlo, y el registro no contiene ciudad, dirección IP ni coordenadas.

**Retención.** Los registros se conservan un año. Los últimos 30 días responden de inmediato; los registros más antiguos vienen del archivo y tardan más.

## Cómo funciona

Llama a `GET /v1/activity` con `Authorization: Bearer <credential>`. La credencial necesita el permiso de lectura de actividad a nivel de organización; una credencial limitada a registros no lo tiene. La organización es siempre la de la credencial: no hay ningún parámetro que nombre otra.

Todos los parámetros son opcionales:

| Parámetro | Significado |
|---|---|
| `from`, `to` | milisegundos Unix, UTC; `from` inclusivo, `to` exclusivo |
| `kind` | uno o más tipos, separados por comas |
| `file_sha256` | 64 caracteres hexadecimales en minúscula: todos los eventos de ese archivo |
| `limit` | de 1 a 500, por defecto 100 |
| `cursor` | el `next_cursor` de la página anterior, sin cambios |

Cualquier otro parámetro, uno repetido o vacío, o un valor no válido es `400 invalid_query`, y no se lee nada. La respuesta viene con lo más reciente primero: `{"items":[...],"next_cursor":<string|null>,"archive_searched":<bool>}`. Sigue `next_cursor` hasta que sea `null`. `archive_searched` te indica que la lectura llegó más allá de los últimos 30 días. Una lectura puede retroceder como máximo 366 días por llamada.

Los registros aparecen unos segundos después de la llamada, no al instante. El registro ocurre después de la respuesta y nunca la modifica: si no se puede escribir en el registro, la llamada se responde como de costumbre. Una descarga desde Datos o Archivos se registra cuando comienza; una descarga desde la API de IA se registra cuando la transferencia se completa. La API de IA también ofrece `GET /v1/activity` en `https://ai.inovacc.dev` para sus propias llamadas, con `from` y `to` como instantes RFC 3339; leerlo allí no se cobra.

## Primeros pasos

Necesitas una credencial con el permiso de lectura de actividad ([Autenticación](/es/guides/authentication/)).

1. **Haz una llamada para registrar.** Escribe un registro en [Datos](/es/products/data/) o carga un archivo en [Archivos](/es/products/files/).
2. **Lee los eventos más recientes.** `GET /v1/activity?limit=10` (consulta [los ejemplos](#example)). Tu llamada está ahí como `api.call`, con su plantilla de ruta y su estado, seguida de su `record.write` o `file.upload.completed`.
3. **Filtra por tipo.** `GET /v1/activity?kind=api.call&limit=50` muestra solo llamadas; mira `status` y `error_code` para encontrar rechazos.
4. **Sigue un archivo.** Toma el `file_sha256` de tu carga y llama a `GET /v1/activity?file_sha256=<hash>`: se listan todas las cargas, descargas y eliminaciones de ese contenido.
5. **Pagina.** Pasa el `next_cursor` de vuelta como `cursor` hasta que sea `null`.

## Casos de uso

**Una respuesta de auditoría.** Un cliente pregunta quién eliminó un registro el martes pasado. Filtra `kind=record.delete` con `from` y `to` alrededor de ese día; el evento nombra al actor y `related` nombra la base de datos, la colección y el registro.

**Prueba de entrega.** Un equipo de cumplimiento debe demostrar que un informe llegó a un socio. El evento `file.download` lleva el SHA-256 y el tamaño de los bytes enviados, y la hora, que se pueden cotejar con el archivo original.

**Salud de una integración.** Una integración empieza a fallar por la noche. Filtrar `kind=api.call` para esa ventana muestra el `status` y el `error_code` de cada llamada hecha con la clave de la integración, por ejemplo una racha de `429 rate_limited` que señala la falta de una espera creciente.

## Límites y precios

| Límite | Valor |
|---|---|
| Retención | un año; los últimos 30 días responden de inmediato |
| Rango de una lectura | 366 días |
| Tamaño de página | 1 a 500 (por defecto 100) |
| Demora antes de que un evento sea legible | unos segundos |
| Tasa | 600 solicitudes por minuto por titular de credencial, por ubicación |

**Precios:** a consultar.

## Errores

| Estado | Código | Qué significa y qué hacer |
|---|---|---|
| 400 | `invalid_query` | Un parámetro es desconocido, está repetido, vacío o no es válido; corrige la consulta. |
| 401 | `invalid_credentials` | Envía una credencial válida. |
| 403 | `forbidden` | La credencial no tiene el permiso de lectura de actividad. |
| 429 | `rate_limited` | Reduce el ritmo. |
| 503 | `service_unavailable` | No se puede leer el registro ahora; reintenta más tarde. |

## Buenas prácticas

- **Filtra en el servidor**: pasa `kind`, `from` y `to` en lugar de leer todo y filtrar en tu código.
- **Conserva el `at_ms` más reciente que procesaste** y lee desde ahí en la siguiente ejecución, siguiendo los cursores hasta el final.
- **Usa `file_sha256`** para rastrear un archivo a través de cargas, descargas y procesamiento de IA.
- **Espera unos segundos de demora**; no trates como un fallo la ausencia de un evento recién generado.
- **Ignora las claves que no conozcas**: los registros pueden ganar campos.
- **Da a cada integración su propia clave**, para que `actor_id` te diga cuál actuó.

## Relacionados

- [Datos](/es/products/data/), [Archivos](/es/products/files/), [Eventos](/es/products/events/)
- [Chat con IA](/es/products/ai.chat/): uso y costo por clave y ruta
- [Autenticación](/es/guides/authentication/), [Errores](/es/guides/errors/), [Límites](/es/guides/limits/)

## Endpoints

- GET /v1/activity

## Ejemplo

```sh
curl -X GET "https://data.inovacc.dev/v1/activity" -H "Authorization: Bearer $INOVACC_API_KEY"
```