> ## 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 > Liste eventos individuais em um intervalo de tempo, do mais recente para o mais antigo, com suas propriedades. Opcionalmente, filtre por nome do evento, propriedades do evento ou pelo distinct_id de um visitante. O intervalo inclui o valor inicial e exclui o final, e IDs de eventos duplicados são retornados uma única vez, de modo que uma busca no intervalo de um bucket de gráfico com os mesmos filtros lista exatamente os eventos que esse bucket contabilizou. Uma página comporta até 100 eventos; passe next_cursor como cursor para a página seguinte até que ele seja nulo. A primeira página captura um instantâneo do relógio do ClickHouse antes de ler suas linhas, e seu cursor o carrega, então cada página da sequência, incluindo a primeira, lê apenas entregas recebidas em ou antes desse instantâneo e expira eventos de retenção conforme ele: nenhum evento se repete ou é ignorado, e eventos recebidos após o instantâneo, incluindo uma redelivery que revise um evento listado, aparecem somente quando a paginação recomeça sem um cursor. Há uma janela que desfoca essa fronteira: o ClickHouse marca o recebimento com segundos inteiros quando uma inserção começa e confirma suas linhas quando ela termina, então uma entrega marcada no segundo do instantâneo ou antes dele, mas que é confirmada após a leitura da primeira página, está dentro da sequência, mas ausente da primeira página; ela entra a partir da próxima página, na qual um evento não listado que ela adiciona ou move à frente do cursor é ignorado e um evento listado que uma redelivery com hash menor move para trás do cursor se repete em sua posição revisada. Um cursor que não decodifica, ou um de outra lista, retorna 400. Uma página cujos eventos excedem o limite de tamanho da resposta retorna 413; solicite um limite menor. ## OpenAPI ````yaml https://apigw.mka1.com/speakeasy.json?language=pt-BR post /api/v1/analytics/projects/{id}/events/search openapi: 3.1.1 info: title: MKA1 API version: 1.1.0 description: >- A API MKA1 é uma API RESTful que fornece acesso à plataforma MKA1. Aprenda como começar a usar a API e o SDK TypeScript [aqui](https://mka1.apidocumentation.com/guides/getting-started). license: name: Proprietário 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: >- Gerencie permissões para recursos LLM. Crie recursos, conceda/revoque permissões e exclua recursos. Apenas os proprietários dos recursos podem conceder, revogar ou excluir permissões. x-displayName: Autorização de Recurso - name: Embeddings description: >- Endpoints da API de incorporação de texto para gerar representações vetoriais de texto. Crie incorporações semânticas para busca, clustering e correspondência de similaridade usando vários modelos de incorporação. x-displayName: Incorporações - name: Feedback description: >- API de feedback do usuário para avaliar e comentar sobre as conclusões de chat. Coleta de classificações de positivo/negativo e feedback detalhado para melhorar as respostas do modelo e acompanhar a satisfação do usuário. x-displayName: Feedback - name: Images description: >- Pontos de extremidade da API de geração de imagens para criar imagens a partir de descrições de texto. Gere imagens com controle sobre tamanho, qualidade e estilo. x-displayName: Imagens - name: MCP Vault description: >- API do cofre MCP para armazenar configurações de servidor MCP de propriedade do usuário e credenciais criptografadas. Os agentes referenciam IDs de cofre para que os segredos sejam resolvidos apenas no momento da execução da ferramenta. x-displayName: Cofre MCP - name: Speech description: >- Pontos de extremidade da API de fala para processamento de áudio. Converta texto em fala com som natural (TTS) ou transcreva fala em texto (STT) em diferentes idiomas. x-displayName: Discurso - name: Usage description: >- API de rastreamento de uso e análise para monitoramento do consumo de tokens, contagem de solicitações e análise de custos. Veja estatísticas detalhadas por usuário, modelo e período de tempo. x-displayName: Uso - name: Extract description: >- API de extração de dados estruturados para extrair informações de arquivos. Defina esquemas JSON para extrair dados estruturados de imagens, PDFs e documentos. Suporta modelos de esquema reutilizáveis. x-displayName: Extração - name: Text Classification description: >- API de classificação de texto para categorizar textos em rótulos predefinidos. Use modelos de IA para classificar o conteúdo textual para análise de sentimento, categorização de tópicos e moderação de conteúdo. x-displayName: Classificação de Texto - name: Responses description: >- API de respostas com agentes para criar agentes de IA com uso autônomo de ferramentas. Crie assistentes conversacionais que podem usar pesquisa na web, operações de arquivos, geração de imagens, execução de código, simulação de uso de computador e integrações MCP. Suporta processamento em segundo plano, streaming e monitoramento de status em tempo real. x-displayName: Respostas - name: Files description: >- API de gerenciamento de arquivos para upload, armazenamento e gerenciamento de arquivos com expiração automática e integração com S3. Faça upload de arquivos que podem ser usados com Assistentes, Armazenamentos Vetoriais e outras funcionalidades. Os arquivos são armazenados no S3 com metadados rastreados no PostgreSQL. Suporta limpeza automática de arquivos expirados. x-displayName: Arquivos - name: Vector Stores description: >- API de armazenamento de vetores para armazenar e pesquisar documentos usando embeddings. Crie armazenamentos de vetores, faça upload de arquivos com divisão automática e geração de embeddings, e realize pesquisas semânticas. Os arquivos são processados de forma assíncrona usando fluxos de trabalho Temporais para durabilidade. Suporta limpeza automática de armazenamentos expirados e LanceDB para armazenamento eficiente de vetores. x-displayName: Armazenamentos de Vetores - name: Conversations description: >- API de gerenciamento de conversas para armazenar e recuperar o estado da conversa durante chamadas à API de Resposta. Crie conversas, adicione itens (mensagens do usuário, mensagens do assistente, mensagens do sistema) e mantenha o histórico da conversa. Suporta rastreamento de metadados e gerenciamento de estado de diálogo em múltiplas interações. x-displayName: Conversa - name: Guardrails description: >- API de diretrizes de segurança de IA para configurar moderação de conteúdo e políticas de segurança. Configure listas de palavras proibidas, detecção de injeção de prompts e prevenção de vazamento de prompts do sistema. As diretrizes aplicam-se a todas as solicitações de uma conta e podem ser testadas antes da implementação. x-displayName: Guarda-corpos - name: Models description: >- API de listagem de modelos para descobrir modelos disponíveis. Retorna IDs de modelos, propriedade e metadados de todos os modelos registrados no gateway. x-displayName: Modelos - name: Skills description: >- API de habilidades para gerenciar pacotes versionados de instruções e arquivos seguindo o padrão de Habilidades do Agente. Crie, versionar e baixe pacotes de habilidades reutilizáveis que incluam manifestos SKILL.md para ambientes de agentes. x-displayName: Habilidades - name: Chat Completions description: >- **Obsoleto: Use a API de Respostas (`/api/v1/llm/responses`) em vez disso.** Endpoints de conclusão de chat com suporte para streaming, chamadas de ferramentas e múltiplos provedores. x-deprecated: true x-displayName: Conclusões de Bate-Papo - name: Batches x-displayName: Lotes - name: Evals x-displayName: Avaliações - name: Fine-Tuning x-displayName: Ajuste Fino - name: Memory Stores x-displayName: Armazenamentos de Memória - name: Prompts x-displayName: Sugestões - name: API Key x-displayName: Chave da API - name: Session x-displayName: Sessão - name: Organization x-displayName: Organização - name: Cluster Admin x-displayName: Administrador do cluster - name: Sessions description: Crie, inspecione, acesse e encerre sessões de sandbox. x-displayName: Sessões - name: Browser description: >- Conecte-se às sessões do navegador através do proxy da porta do gateway. As sessões do navegador expõem um endpoint do Chrome DevTools Protocol na porta 9222. x-displayName: Navegador - name: Execution description: >- Executar comandos shell e código dentro de uma sessão de sandbox existente. x-displayName: Execução - name: Workspace description: >- Inspecione o manifesto do espaço de trabalho, transfira arquivos ou arquivos compactados e baixe artefatos gerados. x-displayName: Espaço de trabalho - name: Sandbox Usage description: >- Agregue estatísticas de uso da sandbox entre sessões, execução e operações do espaço de trabalho. x-displayName: Uso do Sandbox - name: Sandbox Pricing description: >- Gerenciamento de cluster-admin da tabela de preços de computação da sandbox usada para gastos orçados. x-displayName: Preço da Sandbox - name: schema-3_other x-displayName: outro - name: Agents description: Crie e gerencie definições de agentes reutilizáveis. x-displayName: Agentes - name: Agent Versions description: >- Inspecione o histórico de configuração de um agente e reverta para uma versão anterior. x-displayName: Versões do Agente - name: Agent Runs description: Execute agentes salvos e inspecione os resultados da execução persistidos. x-displayName: Executa Agente - name: Agent Connectors description: >- Conecte agentes salvos a canais de mensagens externos, como o Telegram, incluindo troca de texto, foto e documentos compatíveis. x-displayName: Conectores de Agente - name: Agent Schedules description: Crie e gerencie execuções de agentes salvos agendadas ou recorrentes. x-displayName: Agendas de Agentes - name: schema-4_other x-displayName: outro - name: Budgets x-displayName: Orçamentos - name: Settings x-displayName: Configurações - name: Compute Jobs x-displayName: Jobs de Computação - name: Compute Services x-displayName: Serviços de Computação - name: Compute Catalog x-displayName: Catálogo de Computação - name: Compute Volumes x-displayName: Calcular volumes - name: Compute Pricing x-displayName: Calcular Preços - name: Compute Secrets x-displayName: Calcular Segredos - name: Compute Usage x-displayName: Uso de Computação - name: Compute Tenants x-displayName: Calcular Inquilinos - description: Criar, listar, ler, atualizar e excluir repositórios. name: Repositories x-displayName: Repositórios - name: Tracking Experiments description: Criar e consultar experimentos de locatário. x-displayName: Rastreamento de Experimentos - name: Tracking Runs description: Registrar e recuperar parâmetros, métricas e tags da execução. x-displayName: Acompanhamento de execuções - name: analytics.projects x-displayName: Projetos description: Criar, listar, renomear e arquivar projetos de análise. - name: analytics.keys x-displayName: Capturar chaves description: Criar e revogar chaves do projeto para enviar eventos. - name: analytics x-displayName: Eventos description: Envie eventos e consulte contagens de eventos ou visitantes únicos. - name: analytics.events x-displayName: Busca de eventos description: >- Liste eventos individuais com suas propriedades, do mais recente para o mais antigo. - name: analytics.visitors x-displayName: Busca de visitantes description: >- Liste os visitantes por sua atividade mais recente, com os horários de primeira e última visualização. - name: generators x-displayName: geradores - name: generations x-displayName: gerações - name: formats x-displayName: formatos paths: /api/v1/analytics/projects/{id}/events/search: post: tags: - analytics.events summary: Pesquisar eventos em um intervalo de tempo description: >- Liste eventos individuais em um intervalo de tempo, do mais recente para o mais antigo, com suas propriedades. Opcionalmente, filtre por nome do evento, propriedades do evento ou pelo distinct_id de um visitante. O intervalo inclui o valor inicial e exclui o final, e IDs de eventos duplicados são retornados uma única vez, de modo que uma busca no intervalo de um bucket de gráfico com os mesmos filtros lista exatamente os eventos que esse bucket contabilizou. Uma página comporta até 100 eventos; passe next_cursor como cursor para a página seguinte até que ele seja nulo. A primeira página captura um instantâneo do relógio do ClickHouse antes de ler suas linhas, e seu cursor o carrega, então cada página da sequência, incluindo a primeira, lê apenas entregas recebidas em ou antes desse instantâneo e expira eventos de retenção conforme ele: nenhum evento se repete ou é ignorado, e eventos recebidos após o instantâneo, incluindo uma redelivery que revise um evento listado, aparecem somente quando a paginação recomeça sem um cursor. Há uma janela que desfoca essa fronteira: o ClickHouse marca o recebimento com segundos inteiros quando uma inserção começa e confirma suas linhas quando ela termina, então uma entrega marcada no segundo do instantâneo ou antes dele, mas que é confirmada após a leitura da primeira página, está dentro da sequência, mas ausente da primeira página; ela entra a partir da próxima página, na qual um evento não listado que ela adiciona ou move à frente do cursor é ignorado e um evento listado que uma redelivery com hash menor move para trás do cursor se repete em sua posição revisada. Um cursor que não decodifica, ou um de outra lista, retorna 400. Uma página cujos eventos excedem o limite de tamanho da resposta retorna 413; solicite um limite menor. operationId: analytics_events_search parameters: - in: path name: id schema: type: string minLength: 1 maxLength: 128 pattern: ^[^\u0000]*$ description: ID do projeto de análises. 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: Sucesso content: application/json: schema: $ref: '#/components/schemas/AnalyticsEventSearchResponse' '400': description: Falha na solicitação content: application/json: schema: $ref: '#/components/schemas/AnalyticsError' '401': description: Falha na solicitação content: application/json: schema: $ref: '#/components/schemas/AnalyticsError' '403': description: Falha na solicitação content: application/json: schema: $ref: '#/components/schemas/AnalyticsError' '404': description: Falha na solicitação content: application/json: schema: $ref: '#/components/schemas/AnalyticsError' '409': description: Falha na solicitação content: application/json: schema: $ref: '#/components/schemas/AnalyticsError' '413': description: Falha na solicitação content: application/json: schema: $ref: '#/components/schemas/AnalyticsError' '415': description: Falha na solicitação content: application/json: schema: $ref: '#/components/schemas/AnalyticsError' '429': description: Falha na solicitação content: application/json: schema: $ref: '#/components/schemas/AnalyticsError' '500': description: Falha na solicitação content: application/json: schema: $ref: '#/components/schemas/AnalyticsError' '503': description: Falha na solicitação 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: >- Início do intervalo de tempo, inclusive. Use um carimbo de data/hora ISO 8601 com Z para UTC ou um deslocamento como -07:00. Deve ser anterior a to. examples: - '2026-09-01T00:00:00Z' to: type: string format: date-time description: >- Fim do intervalo de tempo, exclusivo. Use um timestamp ISO 8601 com Z para UTC ou um deslocamento como -07:00. Deve ser posterior a from. examples: - '2026-09-02T00:00:00Z' event_name: description: >- Inclua apenas eventos com este nome exato. Omita para incluir todos os nomes de eventos. examples: - page_view type: string minLength: 1 maxLength: 255 filters: default: [] description: >- Filtros de propriedade combinados com AND. Um evento deve corresponder a todos os filtros. maxItems: 10 type: array items: type: object properties: property: type: string minLength: 1 maxLength: 128 pattern: ^[^\u0000]*$ description: >- Propriedade do evento para filtrar. Os nomes das propriedades são chaves literais, não caminhos aninhados. examples: - plan op: type: string enum: - eq - neq - gt - gte - lt - lte - exists - not_exists description: >- Operador de comparação. gt, gte, lt e lte exigem um valor numérico. exists e not_exists verificam se a propriedade está presente e não গ্রহণam um valor. value: description: >- Valor a comparar. O número 1 difere da string '1'. Omita para exists e not_exists. anyOf: - type: string maxLength: 4096 pattern: ^[^\u0000]*$ - type: number - type: boolean - type: 'null' required: - property - op additionalProperties: false distinct_id: description: Inclua apenas eventos enviados com este exact distinct_id. type: string minLength: 1 maxLength: 255 pattern: ^[^\u0000]*$ limit: default: 50 description: Número máximo de linhas nesta página. type: integer minimum: 1 maximum: 100 cursor: type: string minLength: 1 maxLength: 4096 description: >- Cursor opaco de no máximo 4096 caracteres, copiado de next_cursor da página anterior. Omitir na primeira página, que captura o snapshot da sequência completa na qual as leituras ocorrem. Os cursores pertencem a uma lista e a uma ordem de classificação; um cursor que não decodifica, ou um de outra lista, retorna 400. Um cursor é uma posição, não uma capacidade: um que decodifica apenas move o chamador dentro do mesmo projeto. required: - from - to additionalProperties: false AnalyticsEventSearchResponse: type: object properties: events: type: array items: $ref: '#/components/schemas/AnalyticsEvent' description: >- Eventos correspondentes, mais recentes primeiro. Eventos com o mesmo carimbo de data e hora são ordenados por event_id, em ordem decrescente. next_cursor: description: >- Cursor para a próxima página, ou null quando não houver mais linhas. Ele continua a sequência no snapshot da primeira 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: >- ID único para este evento. Reutilize-o ao tentar novamente o mesmo evento. event_name: type: string minLength: 1 maxLength: 255 pattern: ^[^\u0000]*$ description: Nome da ação que você está monitorando. examples: - page_view timestamp: type: string format: date-time description: >- Quando o evento ocorreu. Use um carimbo de data/hora ISO 8601 com Z para UTC ou um deslocamento, como -07:00. Envie carimbos de data/hora atuais para novos eventos. A pesquisa de eventos o retorna em UTC com milissegundos, terminando em Z. examples: - '2026-09-01T12:30:00Z' distinct_id: type: string minLength: 1 maxLength: 255 pattern: ^[^\u0000]*$ description: >- Seu identificador para o visitante. Consultas de visitantes únicos contam valores distintos deste campo, e a busca de visitantes lista um visitante por valor. properties: description: >- Até 100 propriedades do evento. Os valores podem ser strings, números, booleanos ou nulos. Objetos aninhados e arrays não são suportados. 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: `. ````