> ## Documentation Index > Fetch the complete documentation index at: https://docs.mka1.com/llms.txt > Use this file to discover all available pages before exploring further. # Search events > Enumera los eventos individuales en un intervalo de tiempo, primero los más recientes, con sus propiedades. Opcionalmente filtra por nombre del evento, propiedades del evento o el distinct_id de un visitante. El intervalo incluye el valor de inicio y excluye el de fin, y los IDs de eventos duplicados se devuelven una sola vez, de modo que una búsqueda sobre el rango de un bucket de gráfico con los mismos filtros enumera exactamente los eventos que ese bucket contó. Una página contiene hasta 100 eventos; pasa next_cursor como cursor para la página siguiente hasta que sea null. La primera página toma una instantánea del reloj de ClickHouse antes de leer sus filas y su cursor la lleva consigo, por lo que cada página de la secuencia, incluida la primera, solo lee entregas recibidas en o antes de esa instantánea y deja fuera de la retención los eventos tal como existían en ese momento: ningún evento se repite ni se omite, y los eventos recibidos después de la instantánea, incluida una nueva entrega que revisa un evento ya listado, aparecen solo cuando la paginación se reinicia sin un cursor. Una ventana difumina ese límite: ClickHouse marca un acuse de recibo con segundos enteros cuando comienza una inserción y confirma sus filas cuando termina, por lo que una entrega marcada en o antes del segundo de la instantánea que se confirma después de leer la primera página está dentro de la secuencia pero ausente de la primera página; se incorpora desde la página siguiente, donde se omite un evento no listado que añade o adelanta frente al cursor y se repite en su posición revisada un evento listado que una nueva entrega con hash menor mueve detrás del cursor. Un cursor que no se puede decodificar, o uno de otra lista, devuelve 400. Una página cuyos eventos superan el límite de tamaño de la respuesta devuelve 413; solicita un límite menor. ## OpenAPI ````yaml https://apigw.mka1.com/speakeasy.json?language=es post /api/v1/analytics/projects/{id}/events/search openapi: 3.1.1 info: title: MKA1 API version: 1.1.0 description: >- La API MKA1 es una API RESTful que proporciona acceso a la plataforma MKA1. Aprende cómo comenzar con la API y el SDK de TypeScript [aquí](https://mka1.apidocumentation.com/guides/getting-started). license: name: Propietario servers: - url: https://apigw.mka1.com description: MKA1 API Gateway - url: / description: Relative server URL (configurable via SDK constructor) security: [] tags: - name: Resource Authorization description: >- Gestiona permisos para recursos LLM. Crea recursos, otorga/revoca permisos y elimina recursos. Solo los propietarios de recursos pueden otorgar, revocar o eliminar permisos. x-displayName: Autorización de Recursos - name: Embeddings description: >- Puntos finales de la API de incrustación de texto para generar representaciones vectoriales del texto. Crea incrustaciones semánticas para búsqueda, agrupamiento y coincidencia de similitudes utilizando varios modelos de incrustación. x-displayName: Incrustaciones - name: Feedback description: >- API de retroalimentación del usuario para calificar y comentar sobre las completaciones de chat. Recopila calificaciones de pulgares arriba/abajo y comentarios detallados para mejorar las respuestas del modelo y rastrear la satisfacción del usuario. x-displayName: Retroalimentación - name: Images description: >- Puntos finales de la API de generación de imágenes para crear imágenes a partir de descripciones de texto. Genera imágenes con control sobre el tamaño, la calidad y el estilo. x-displayName: Imágenes - name: MCP Vault description: >- API de bóveda MCP para almacenar configuraciones de servidor MCP propiedad del usuario y credenciales encriptadas. Los agentes hacen referencia a los ID de la bóveda para que los secretos se resuelvan solo en el momento de la ejecución de la herramienta. x-displayName: Bóveda MCP - name: Speech description: >- Puntos finales de la API de voz para el procesamiento de audio. Convierte texto en habla natural (TTS) o transcribe el habla a texto (STT) en diferentes idiomas. x-displayName: Discurso - name: Usage description: >- API de seguimiento de uso y análisis para monitorear el consumo de tokens, la cantidad de solicitudes y el análisis de costos. Visualiza estadísticas detalladas por usuario, modelo y período de tiempo. x-displayName: Uso - name: Extract description: >- API de extracción de datos estructurados para extraer información de archivos. Define esquemas JSON para extraer datos estructurados de imágenes, PDFs y documentos. Soporta plantillas de esquemas reutilizables. x-displayName: Extracción - name: Text Classification description: >- API de clasificación de texto para categorizar texto en etiquetas predefinidas. Utilice modelos de IA para clasificar el contenido del texto para análisis de sentimientos, categorización de temas y moderación de contenido. x-displayName: Clasificación de Texto - name: Responses description: >- API de respuestas impulsadas por agentes para crear agentes de IA con uso autónomo de herramientas. Crea asistentes conversacionales que pueden utilizar búsqueda en la web, operaciones con archivos, generación de imágenes, ejecución de código, simulación de uso de computadoras e integraciones de MCP. Soporta procesamiento en segundo plano, transmisión y seguimiento de estado en tiempo real. x-displayName: Respuestas - name: Files description: >- API de gestión de archivos para cargar, almacenar y gestionar archivos con expiración automática e integración con S3. Carga archivos que se pueden usar con Asistentes, Almacenes Vectoriales y otras funciones. Los archivos se almacenan en S3 con metadatos rastreados en PostgreSQL. Soporta la limpieza automática de archivos expirados. x-displayName: Archivos - name: Vector Stores description: >- API de almacenamiento de vectores para almacenar y buscar documentos utilizando incrustaciones. Crea almacenes de vectores, sube archivos con fragmentación automática y generación de incrustaciones, y realiza búsquedas semánticas. Los archivos se procesan de forma asincrónica utilizando flujos de trabajo de Temporal para durabilidad. Soporta limpieza automática de almacenes caducados y LanceDB para almacenamiento eficiente de vectores. x-displayName: Almacenes de Vectores - name: Conversations description: >- API de gestión de conversaciones para almacenar y recuperar el estado de la conversación a través de llamadas a la API de respuesta. Crea conversaciones, añade elementos (mensajes de usuario, mensajes del asistente, mensajes del sistema) y mantiene el historial de la conversación. Soporta seguimiento de metadatos y gestión del estado del diálogo en múltiples turnos. x-displayName: Conversaciones - name: Guardrails description: >- API de salvaguardias de seguridad de IA para configurar la moderación de contenido y las políticas de seguridad. Configura listas de palabras prohibidas, detección de inyección de mensajes y prevención de filtración de mensajes del sistema. Las salvaguardias se aplican a todas las solicitudes de una cuenta y se pueden probar antes del despliegue. x-displayName: Barandillas - name: Models description: >- API de listado de modelos para descubrir modelos disponibles. Devuelve IDs de modelos, propiedad y metadatos para todos los modelos registrados en la puerta de enlace. x-displayName: Modelos - name: Skills description: >- API de habilidades para gestionar paquetes de instrucciones y archivos versionados siguiendo el estándar de Habilidades del Agente. Crea, versiona y descarga paquetes de habilidades reutilizables que incluyen manifiestos SKILL.md para entornos de agentes. x-displayName: Habilidades - name: Chat Completions description: >- **Obsoleto: Usa la API de Respuestas (`/api/v1/llm/responses`) en su lugar.** Puntos finales de completación de chat con soporte para transmisión, llamadas a herramientas y múltiples proveedores. x-deprecated: true x-displayName: Completaciones de Chat - name: Batches x-displayName: Lotes - name: Evals x-displayName: Evaluaciones - name: Fine-Tuning x-displayName: Ajuste fino - name: Memory Stores x-displayName: Almacenes de memoria - name: Prompts x-displayName: Sugerencias - name: API Key x-displayName: Clave de API - name: Session x-displayName: Sesión - name: Organization x-displayName: Organización - name: Cluster Admin x-displayName: Administrador de clúster - name: Sessions description: Crear, inspeccionar, acceder y terminar sesiones de sandbox. x-displayName: Sesiones - name: Browser description: >- Conéctate a las sesiones del navegador a través del proxy del puerto de la puerta de enlace. Las sesiones del navegador exponen un punto final del Protocolo de DevTools de Chrome en el puerto 9222. x-displayName: Navegador - name: Execution description: >- Ejecutar comandos de shell y código dentro de una sesión de sandbox existente. x-displayName: Ejecución - name: Workspace description: >- Inspeccionar el manifiesto del espacio de trabajo, transferir archivos o archivos comprimidos, y descargar artefactos generados. x-displayName: Espacio de trabajo - name: Sandbox Usage description: >- Agrega estadísticas de uso de sandbox entre sesiones, ejecución y operaciones del espacio de trabajo. x-displayName: Uso de Sandbox - name: Sandbox Pricing description: >- Gestión de administrador de clúster de la tarjeta de tarifas de cómputo del entorno aislado utilizada para el gasto presupuestado. x-displayName: Precios de Sandbox - name: schema-3_other x-displayName: otro - name: Agents description: Crea y gestiona definiciones de agentes reutilizables. x-displayName: Agentes - name: Agent Versions description: >- Inspeccionar el historial de configuración de un agente y revertir a una versión anterior. x-displayName: Versiones de Agente - name: Agent Runs description: >- Ejecutar agentes guardados e inspeccionar los resultados de ejecución persistidos. x-displayName: Ejecuta Agentes - name: Agent Connectors description: >- Conecta agentes guardados a canales de mensajería externos como Telegram, incluyendo intercambio de texto, fotos y documentos compatibles. x-displayName: Conectores de agentes - name: Agent Schedules description: >- Crea y gestiona ejecuciones de agentes programadas o recurrentes guardadas. x-displayName: Horarios de Agentes - name: schema-4_other x-displayName: otro - name: Budgets x-displayName: Presupuestos - name: Settings x-displayName: Configuración - name: Compute Jobs x-displayName: Trabajos de computación - name: Compute Services x-displayName: Servicios de computación - name: Compute Catalog x-displayName: Catálogo de cómputo - name: Compute Volumes x-displayName: Calcular volúmenes - name: Compute Pricing x-displayName: Calcular precios - name: Compute Secrets x-displayName: Calcular secretos - name: Compute Usage x-displayName: Uso de cómputo - name: Compute Tenants x-displayName: Calcular inquilinos - description: Crear, listar, leer, actualizar y eliminar repositorios. name: Repositories x-displayName: Repositorios - name: Tracking Experiments description: Crear y consultar experimentos del inquilino. x-displayName: Seguimiento de experimentos - name: Tracking Runs description: Registrar y recuperar parámetros, métricas y etiquetas de ejecución. x-displayName: Seguimiento de ejecuciones - name: analytics.projects x-displayName: Proyectos description: Crear, listar, renombrar y archivar proyectos de análisis. - name: analytics.keys x-displayName: Capturar teclas description: Crear y revocar claves de proyecto para enviar eventos. - name: analytics x-displayName: Eventos description: Enviar eventos y consultar el número de eventos o visitantes únicos. - name: analytics.events x-displayName: Búsqueda de eventos description: >- Enumere los eventos individuales con sus propiedades, primero los más recientes. - name: analytics.visitors x-displayName: Búsqueda de visitantes description: >- Lista a los visitantes según su actividad más reciente, con las horas de primera y última vez que se les vio. - name: generators x-displayName: generadores - name: generations x-displayName: generaciones - name: formats x-displayName: formatos paths: /api/v1/analytics/projects/{id}/events/search: post: tags: - analytics.events summary: Buscar eventos en un intervalo de tiempo description: >- Enumera los eventos individuales en un intervalo de tiempo, primero los más recientes, con sus propiedades. Opcionalmente filtra por nombre del evento, propiedades del evento o el distinct_id de un visitante. El intervalo incluye el valor de inicio y excluye el de fin, y los IDs de eventos duplicados se devuelven una sola vez, de modo que una búsqueda sobre el rango de un bucket de gráfico con los mismos filtros enumera exactamente los eventos que ese bucket contó. Una página contiene hasta 100 eventos; pasa next_cursor como cursor para la página siguiente hasta que sea null. La primera página toma una instantánea del reloj de ClickHouse antes de leer sus filas y su cursor la lleva consigo, por lo que cada página de la secuencia, incluida la primera, solo lee entregas recibidas en o antes de esa instantánea y deja fuera de la retención los eventos tal como existían en ese momento: ningún evento se repite ni se omite, y los eventos recibidos después de la instantánea, incluida una nueva entrega que revisa un evento ya listado, aparecen solo cuando la paginación se reinicia sin un cursor. Una ventana difumina ese límite: ClickHouse marca un acuse de recibo con segundos enteros cuando comienza una inserción y confirma sus filas cuando termina, por lo que una entrega marcada en o antes del segundo de la instantánea que se confirma después de leer la primera página está dentro de la secuencia pero ausente de la primera página; se incorpora desde la página siguiente, donde se omite un evento no listado que añade o adelanta frente al cursor y se repite en su posición revisada un evento listado que una nueva entrega con hash menor mueve detrás del cursor. Un cursor que no se puede decodificar, o uno de otra lista, devuelve 400. Una página cuyos eventos superan el límite de tamaño de la respuesta devuelve 413; solicita un límite menor. operationId: analytics_events_search parameters: - in: path name: id schema: type: string minLength: 1 maxLength: 128 pattern: ^[^\u0000]*$ description: ID del proyecto de análisis. required: true description: ID of the analytics project. requestBody: required: true content: application/json: example: from: '2026-09-17T07:00:00Z' to: '2026-09-17T08:00:00Z' event_name: page_view filters: - property: plan op: eq value: pro distinct_id: visitor-123 limit: 50 schema: $ref: '#/components/schemas/AnalyticsEventSearchRequest' responses: '200': description: Éxito content: application/json: schema: $ref: '#/components/schemas/AnalyticsEventSearchResponse' '400': description: Solicitud fallida content: application/json: schema: $ref: '#/components/schemas/AnalyticsError' '401': description: Solicitud fallida content: application/json: schema: $ref: '#/components/schemas/AnalyticsError' '403': description: Solicitud fallida content: application/json: schema: $ref: '#/components/schemas/AnalyticsError' '404': description: Solicitud fallida content: application/json: schema: $ref: '#/components/schemas/AnalyticsError' '409': description: Solicitud fallida content: application/json: schema: $ref: '#/components/schemas/AnalyticsError' '413': description: Solicitud fallida content: application/json: schema: $ref: '#/components/schemas/AnalyticsError' '415': description: Solicitud fallida content: application/json: schema: $ref: '#/components/schemas/AnalyticsError' '429': description: Solicitud fallida content: application/json: schema: $ref: '#/components/schemas/AnalyticsError' '500': description: Solicitud fallida content: application/json: schema: $ref: '#/components/schemas/AnalyticsError' '503': description: Solicitud fallida content: application/json: schema: $ref: '#/components/schemas/AnalyticsError' security: - bearerAuth: [] x-codeSamples: - lang: python label: Python (SDK) source: |- from meetkai_mka1 import SDK from meetkai_mka1.utils import parse_datetime with SDK( bearer_auth="", ) as sdk: res = sdk.analytics.events.search(id="", from_=parse_datetime("2026-09-17T07:00:00Z"), to=parse_datetime("2026-09-17T08:00:00Z"), event_name="page_view", filters=[ { "property": "plan", "op": "eq", "value": "pro", }, ], distinct_id="visitor-123", limit=50) # Handle response print(res) - lang: typescript label: Typescript (SDK) source: |- import { SDK } from "@meetkai/mka1"; const sdk = new SDK({ bearerAuth: "", }); async function run() { const result = await sdk.analytics.events.search({ id: "", analyticsEventSearchRequest: { from: new Date("2026-09-17T07:00:00Z"), to: new Date("2026-09-17T08:00:00Z"), eventName: "page_view", filters: [ { property: "plan", op: "eq", value: "pro", }, ], distinctId: "visitor-123", }, }); console.log(result); } run(); - lang: csharp label: CSharp (SDK) source: |- using MeetKai.MKA1; using MeetKai.MKA1.Types.Components; using System; using System.Collections.Generic; var sdk = new SDK(bearerAuth: ""); var res = await sdk.Analytics.Events.SearchAsync( id: "", body: new AnalyticsEventSearchRequest() { From = System.DateTime.Parse("2026-09-17T07:00:00Z").ToUniversalTime(), To = System.DateTime.Parse("2026-09-17T08:00:00Z").ToUniversalTime(), EventName = "page_view", Filters = new List() { new AnalyticsEventSearchRequestFilter() { Property = "plan", Op = AnalyticsEventSearchRequestOp.Eq, Value = AnalyticsEventSearchRequestValue.CreateStr( "pro" ), }, }, DistinctId = "visitor-123", } ); // handle response components: schemas: AnalyticsEventSearchRequest: type: object properties: from: type: string format: date-time description: >- Inicio del intervalo de tiempo, inclusivo. Use una marca de tiempo ISO 8601 con Z para UTC o un desplazamiento como -07:00. Debe ser anterior a to. examples: - '2026-09-01T00:00:00Z' to: type: string format: date-time description: >- Fin del intervalo de tiempo, exclusivo. Utilice una marca de tiempo ISO 8601 con Z para UTC o un desfase como -07:00. Debe ser posterior a from. examples: - '2026-09-02T00:00:00Z' event_name: description: >- Solo incluye eventos con este nombre exacto. Omite para incluir todos los nombres de eventos. examples: - page_view type: string minLength: 1 maxLength: 255 filters: default: [] description: >- Filtros de propiedades combinados con AND. Un evento debe coincidir con todos los filtros. maxItems: 10 type: array items: type: object properties: property: type: string minLength: 1 maxLength: 128 pattern: ^[^\u0000]*$ description: >- Propiedad del evento para filtrar. Los nombres de las propiedades son claves literales, no rutas anidadas. examples: - plan op: type: string enum: - eq - neq - gt - gte - lt - lte - exists - not_exists description: >- Operador de comparación. gt, gte, lt y lte requieren un valor numérico. exists y not_exists verifican si la propiedad está presente y no toman un valor. value: description: >- Valor a comparar. El número 1 difiere de la cadena '1'. Omitir para exists y not_exists. anyOf: - type: string maxLength: 4096 pattern: ^[^\u0000]*$ - type: number - type: boolean - type: 'null' required: - property - op additionalProperties: false distinct_id: description: Solo incluye eventos enviados con este exacto distinct_id. type: string minLength: 1 maxLength: 255 pattern: ^[^\u0000]*$ limit: default: 50 description: Número máximo de filas en esta página. type: integer minimum: 1 maximum: 100 cursor: type: string minLength: 1 maxLength: 4096 description: >- Cursor opaco de como máximo 4096 caracteres, copiado de next_cursor de la página anterior. Omítalo para la primera página, que toma la instantánea en la que se basa toda la secuencia de lectura. Los cursores pertenecen a una lista y un orden de clasificación; un cursor que no decodifica, o uno de otra lista, devuelve 400. Un cursor es una posición, no una capacidad: uno que decodifica solo mueve al llamante dentro del mismo proyecto. required: - from - to additionalProperties: false AnalyticsEventSearchResponse: type: object properties: events: type: array items: $ref: '#/components/schemas/AnalyticsEvent' description: >- Eventos coincidentes, primero los más recientes. Los eventos con la misma marca de tiempo se ordenan por event_id, en orden descendente. next_cursor: description: >- Cursor para la siguiente página, o null cuando no hay más filas. Continúa la secuencia en la instantánea que tomó su primera página. type: - string - 'null' required: - events - next_cursor additionalProperties: false AnalyticsError: type: object properties: code: type: string message: type: string required: - code - message additionalProperties: false AnalyticsEvent: type: object properties: event_id: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ description: >- Identificador único para este evento. Vuelva a usarlo al reintentar el mismo evento. event_name: type: string minLength: 1 maxLength: 255 pattern: ^[^\u0000]*$ description: Nombre de la acción que estás rastreando. examples: - page_view timestamp: type: string format: date-time description: >- Cuándo ocurrió el evento. Usa una marca de tiempo ISO 8601 con Z para UTC o un desplazamiento como -07:00. Envía marcas de tiempo actuales para eventos nuevos. La búsqueda de eventos la devuelve en UTC con milisegundos, terminando en Z. examples: - '2026-09-01T12:30:00Z' distinct_id: type: string minLength: 1 maxLength: 255 pattern: ^[^\u0000]*$ description: >- Tu identificador para el visitante. Las consultas de visitantes únicos cuentan los valores distintos de este campo, y la búsqueda de visitantes muestra un visitante por cada valor. properties: description: >- Hasta 100 propiedades de evento. Los valores pueden ser cadenas, números, booleanos o null. Los objetos y arreglos anidados no son compatibles. type: object propertyNames: type: string minLength: 1 maxLength: 128 pattern: ^[^\u0000]*$ additionalProperties: anyOf: - type: string maxLength: 4096 pattern: ^[^\u0000]*$ - type: number - type: boolean - type: 'null' required: - event_id - event_name - timestamp - distinct_id - properties additionalProperties: false securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: API Key description: >- Gateway auth: send `Authorization: Bearer `. For multi-user server-side integrations, you can also send `X-On-Behalf-Of: `. ````