Python (SDK)

from meetkai_mka1 import SDK
from meetkai_mka1.utils import parse_datetime


with SDK(
    bearer_auth="<YOUR_BEARER_TOKEN_HERE>",
) as sdk:

    res = sdk.analytics.visitors.search(id="<id>", from_=parse_datetime("2026-09-17T07:00:00Z"), to=parse_datetime("2026-09-18T07:00:00Z"), event_name="page_view", filters=[
        {
            "property": "plan",
            "op": "eq",
            "value": "pro",
        },
    ], limit=50)

    # Handle response
    print(res)

import { SDK } from "@meetkai/mka1";

const sdk = new SDK({
  bearerAuth: "<YOUR_BEARER_TOKEN_HERE>",
});

async function run() {
  const result = await sdk.analytics.visitors.search({
    id: "<id>",
    analyticsVisitorSearchRequest: {
      from: new Date("2026-09-17T07:00:00Z"),
      to: new Date("2026-09-18T07:00:00Z"),
      eventName: "page_view",
      filters: [
        {
          property: "plan",
          op: "eq",
          value: "pro",
        },
      ],
    },
  });

  console.log(result);
}

run();

using MeetKai.MKA1;
using MeetKai.MKA1.Types.Components;
using System;
using System.Collections.Generic;

var sdk = new SDK(bearerAuth: "<YOUR_BEARER_TOKEN_HERE>");

var res = await sdk.Analytics.Visitors.SearchAsync(
    id: "<id>",
    body: new AnalyticsVisitorSearchRequest() {
        From = System.DateTime.Parse("2026-09-17T07:00:00Z").ToUniversalTime(),
        To = System.DateTime.Parse("2026-09-18T07:00:00Z").ToUniversalTime(),
        EventName = "page_view",
        Filters = new List<AnalyticsVisitorSearchRequestFilter>() {
            new AnalyticsVisitorSearchRequestFilter() {
                Property = "plan",
                Op = AnalyticsVisitorSearchRequestOp.Eq,
                Value = AnalyticsVisitorSearchRequestValue.CreateStr(
                    "pro"
                ),
            },
        },
    }
);

// handle response

curl --request POST \
  --url https://apigw.mka1.com/api/v1/analytics/projects/{id}/visitors/search \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "from": "2026-09-17T07:00:00Z",
  "to": "2026-09-18T07:00:00Z",
  "event_name": "page_view",
  "filters": [
    {
      "property": "plan",
      "op": "eq",
      "value": "pro"
    }
  ],
  "limit": 50
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    from: '2026-09-17T07:00:00Z',
    to: '2026-09-18T07:00:00Z',
    event_name: 'page_view',
    filters: [{property: 'plan', op: 'eq', value: 'pro'}],
    limit: 50
  })
};

fetch('https://apigw.mka1.com/api/v1/analytics/projects/{id}/visitors/search', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://apigw.mka1.com/api/v1/analytics/projects/{id}/visitors/search",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'from' => '2026-09-17T07:00:00Z',
    'to' => '2026-09-18T07:00:00Z',
    'event_name' => 'page_view',
    'filters' => [
        [
                'property' => 'plan',
                'op' => 'eq',
                'value' => 'pro'
        ]
    ],
    'limit' => 50
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://apigw.mka1.com/api/v1/analytics/projects/{id}/visitors/search"

	payload := strings.NewReader("{\n  \"from\": \"2026-09-17T07:00:00Z\",\n  \"to\": \"2026-09-18T07:00:00Z\",\n  \"event_name\": \"page_view\",\n  \"filters\": [\n    {\n      \"property\": \"plan\",\n      \"op\": \"eq\",\n      \"value\": \"pro\"\n    }\n  ],\n  \"limit\": 50\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://apigw.mka1.com/api/v1/analytics/projects/{id}/visitors/search")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"from\": \"2026-09-17T07:00:00Z\",\n  \"to\": \"2026-09-18T07:00:00Z\",\n  \"event_name\": \"page_view\",\n  \"filters\": [\n    {\n      \"property\": \"plan\",\n      \"op\": \"eq\",\n      \"value\": \"pro\"\n    }\n  ],\n  \"limit\": 50\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://apigw.mka1.com/api/v1/analytics/projects/{id}/visitors/search")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"from\": \"2026-09-17T07:00:00Z\",\n  \"to\": \"2026-09-18T07:00:00Z\",\n  \"event_name\": \"page_view\",\n  \"filters\": [\n    {\n      \"property\": \"plan\",\n      \"op\": \"eq\",\n      \"value\": \"pro\"\n    }\n  ],\n  \"limit\": 50\n}"

response = http.request(request)
puts response.read_body

{
  "visitors": [
    {
      "distinct_id": "<string>",
      "first_seen": "2026-09-17T07:00:00.123Z",
      "last_seen": "2026-09-17T07:00:00.123Z",
      "event_count": 4503599627370495
    }
  ],
  "next_cursor": "<string>"
}

{
  "code": "<string>",
  "message": "<string>"
}

{
  "code": "<string>",
  "message": "<string>"
}

{
  "code": "<string>",
  "message": "<string>"
}

{
  "code": "<string>",
  "message": "<string>"
}

{
  "code": "<string>",
  "message": "<string>"
}

{
  "code": "<string>",
  "message": "<string>"
}

{
  "code": "<string>",
  "message": "<string>"
}

{
  "code": "<string>",
  "message": "<string>"
}

{
  "code": "<string>",
  "message": "<string>"
}

{
  "code": "<string>",
  "message": "<string>"
}

analytics.visitors

Search visitors

Liste visitantes com eventos correspondentes em um intervalo de tempo, em ordem de atividade mais recente primeiro. Cada visitante é um distinct_id com os timestamps do primeiro e do último evento correspondente e a contagem de eventos ao longo de todo o intervalo; assim, para um intervalo que não recebe mais eventos, o número de visitantes em todas as páginas é igual à consulta unique_visitors para o mesmo intervalo e filtros. O intervalo inclui from e exclui to, e IDs de eventos duplicados são contados uma vez. Uma página comporta até 100 visitantes; passe next_cursor como cursor para a página seguinte até que ele seja null. A primeira página faz um snapshot do relógio do ClickHouse antes de ler suas linhas e seu cursor o carrega, então cada página da sequência, inclusive a primeira, lê apenas entregas recebidas em ou antes desse snapshot e expira eventos de retenção conforme ele: um visitante mantém a posição, first_seen, last_seen e event_count com os quais a sequência começou, nenhum visitante se repete ou é pulado, e a atividade recebida após o snapshot aparece somente quando a paginação reinicia sem um cursor. Uma janela desfoca essa fronteira: o ClickHouse carimba o recebimento em segundos inteiros quando um insert começa e confirma suas linhas quando ele termina, então uma entrega carimbada no segundo do snapshot ou antes, mas que se confirma após a leitura da primeira página, está dentro da sequência, porém ausente da primeira página; ela entra a partir da página seguinte, onde um visitante não listado que ela adiciona ou move para frente do cursor é pulado e um visitante listado cujo envio vencedor é movido para trás do cursor por uma redelivery com hash menor se repete com totais revisados; caso contrário, os totais de um visitante listado permanecem como listados. Um cursor que não decodifica, ou um de outra lista, retorna 400.

POST

api

analytics

projects

{id}

visitors

Python (SDK)

from meetkai_mka1 import SDK
from meetkai_mka1.utils import parse_datetime


with SDK(
    bearer_auth="<YOUR_BEARER_TOKEN_HERE>",
) as sdk:

    res = sdk.analytics.visitors.search(id="<id>", from_=parse_datetime("2026-09-17T07:00:00Z"), to=parse_datetime("2026-09-18T07:00:00Z"), event_name="page_view", filters=[
        {
            "property": "plan",
            "op": "eq",
            "value": "pro",
        },
    ], limit=50)

    # Handle response
    print(res)

import { SDK } from "@meetkai/mka1";

const sdk = new SDK({
  bearerAuth: "<YOUR_BEARER_TOKEN_HERE>",
});

async function run() {
  const result = await sdk.analytics.visitors.search({
    id: "<id>",
    analyticsVisitorSearchRequest: {
      from: new Date("2026-09-17T07:00:00Z"),
      to: new Date("2026-09-18T07:00:00Z"),
      eventName: "page_view",
      filters: [
        {
          property: "plan",
          op: "eq",
          value: "pro",
        },
      ],
    },
  });

  console.log(result);
}

run();

using MeetKai.MKA1;
using MeetKai.MKA1.Types.Components;
using System;
using System.Collections.Generic;

var sdk = new SDK(bearerAuth: "<YOUR_BEARER_TOKEN_HERE>");

var res = await sdk.Analytics.Visitors.SearchAsync(
    id: "<id>",
    body: new AnalyticsVisitorSearchRequest() {
        From = System.DateTime.Parse("2026-09-17T07:00:00Z").ToUniversalTime(),
        To = System.DateTime.Parse("2026-09-18T07:00:00Z").ToUniversalTime(),
        EventName = "page_view",
        Filters = new List<AnalyticsVisitorSearchRequestFilter>() {
            new AnalyticsVisitorSearchRequestFilter() {
                Property = "plan",
                Op = AnalyticsVisitorSearchRequestOp.Eq,
                Value = AnalyticsVisitorSearchRequestValue.CreateStr(
                    "pro"
                ),
            },
        },
    }
);

// handle response

curl --request POST \
  --url https://apigw.mka1.com/api/v1/analytics/projects/{id}/visitors/search \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "from": "2026-09-17T07:00:00Z",
  "to": "2026-09-18T07:00:00Z",
  "event_name": "page_view",
  "filters": [
    {
      "property": "plan",
      "op": "eq",
      "value": "pro"
    }
  ],
  "limit": 50
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    from: '2026-09-17T07:00:00Z',
    to: '2026-09-18T07:00:00Z',
    event_name: 'page_view',
    filters: [{property: 'plan', op: 'eq', value: 'pro'}],
    limit: 50
  })
};

fetch('https://apigw.mka1.com/api/v1/analytics/projects/{id}/visitors/search', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://apigw.mka1.com/api/v1/analytics/projects/{id}/visitors/search",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'from' => '2026-09-17T07:00:00Z',
    'to' => '2026-09-18T07:00:00Z',
    'event_name' => 'page_view',
    'filters' => [
        [
                'property' => 'plan',
                'op' => 'eq',
                'value' => 'pro'
        ]
    ],
    'limit' => 50
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://apigw.mka1.com/api/v1/analytics/projects/{id}/visitors/search"

	payload := strings.NewReader("{\n  \"from\": \"2026-09-17T07:00:00Z\",\n  \"to\": \"2026-09-18T07:00:00Z\",\n  \"event_name\": \"page_view\",\n  \"filters\": [\n    {\n      \"property\": \"plan\",\n      \"op\": \"eq\",\n      \"value\": \"pro\"\n    }\n  ],\n  \"limit\": 50\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://apigw.mka1.com/api/v1/analytics/projects/{id}/visitors/search")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"from\": \"2026-09-17T07:00:00Z\",\n  \"to\": \"2026-09-18T07:00:00Z\",\n  \"event_name\": \"page_view\",\n  \"filters\": [\n    {\n      \"property\": \"plan\",\n      \"op\": \"eq\",\n      \"value\": \"pro\"\n    }\n  ],\n  \"limit\": 50\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://apigw.mka1.com/api/v1/analytics/projects/{id}/visitors/search")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"from\": \"2026-09-17T07:00:00Z\",\n  \"to\": \"2026-09-18T07:00:00Z\",\n  \"event_name\": \"page_view\",\n  \"filters\": [\n    {\n      \"property\": \"plan\",\n      \"op\": \"eq\",\n      \"value\": \"pro\"\n    }\n  ],\n  \"limit\": 50\n}"

response = http.request(request)
puts response.read_body

{
  "visitors": [
    {
      "distinct_id": "<string>",
      "first_seen": "2026-09-17T07:00:00.123Z",
      "last_seen": "2026-09-17T07:00:00.123Z",
      "event_count": 4503599627370495
    }
  ],
  "next_cursor": "<string>"
}

{
  "code": "<string>",
  "message": "<string>"
}

{
  "code": "<string>",
  "message": "<string>"
}

{
  "code": "<string>",
  "message": "<string>"
}

{
  "code": "<string>",
  "message": "<string>"
}

{
  "code": "<string>",
  "message": "<string>"
}

{
  "code": "<string>",
  "message": "<string>"
}

{
  "code": "<string>",
  "message": "<string>"
}

{
  "code": "<string>",
  "message": "<string>"
}

{
  "code": "<string>",
  "message": "<string>"
}

{
  "code": "<string>",
  "message": "<string>"
}

Autorizações

Authorization

string

header

obrigatório

Gateway auth: send Authorization: Bearer <mka1-api-key>. For multi-user server-side integrations, you can also send X-On-Behalf-Of: <external-user-id>.

Parâmetros de caminho

string

obrigatório

ID of the analytics project. ID do projeto de análises.

Required string length: 1 - 128

Pattern: ^[^\u0000]*$

Corpo

application/json

from

string<date-time>

obrigatório

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.

Exemplo:

"2026-09-01T00:00:00Z"

string<date-time>

obrigatório

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.

Exemplo:

"2026-09-02T00:00:00Z"

event_name

string

Inclua apenas eventos com este nome exato. Omita para incluir todos os nomes de eventos.

Required string length: 1 - 255

Exemplo:

"page_view"

filters

object[]

Filtros de propriedade combinados com AND. Um evento deve corresponder a todos os filtros.

Maximum array length: 10

Show child attributes

limit

integer

padrão:50

Número máximo de linhas nesta página.

Intervalo obrigatório: 1 <= x <= 100

cursor

string

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 string length: 1 - 4096

Resposta

Sucesso

visitors

object[]

obrigatório

Correspondência de visitantes, os mais recentemente ativos primeiro. Visitantes com o mesmo last_seen são ordenados por distinct_id, em ordem decrescente.

Show child attributes

next_cursor

string | null

obrigatório

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.

⌘I

Responses and conversations

Models and routing

Images and audio

Files and retrieval

Agents

Tools and sandbox

Evals and feedback

Compute

Repositories and datasets

Organizations and access

Usage and budgets

Application utilities

Analytics

Legacy APIs

Additional APIs

Search visitors

Autorizações

Parâmetros de caminho

Corpo

Resposta