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

Enumera los visitantes con eventos coincidentes en un rango de tiempo, mostrando primero los más recientemente activos. Cada visitante es un distinct_id con las marcas de tiempo de su primer y último evento coincidente y su recuento de eventos en todo el rango; por lo tanto, para un rango que no recibe más eventos, el número de visitantes en todas las páginas equivale a la consulta unique_visitors para el mismo rango y filtros. El rango incluye from y excluye to, y los ID de evento duplicados se cuentan una sola vez. Una página contiene hasta 100 visitantes; 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, de modo que cada página de la secuencia, incluida la primera, solo lee entregas recibidas en o antes de esa instantánea y descarta los eventos por antigüedad según ella: un visitante conserva la posición, first_seen, last_seen y event_count con los que empezó la secuencia, no se repite ni se omite ningún visitante, y la actividad recibida después de la instantánea solo aparece cuando la paginación se reinicia sin un cursor. Una ventana difumina ese límite: ClickHouse marca un recibo en segundos enteros cuando empieza una inserción y confirma sus filas cuando termina, así 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 en la primera página; se incorpora desde la página siguiente, donde un visitante no listado que añade o adelanta al cursor se omite y un visitante listado cuyo envío ganador una nueva entrega con menor hash mueve detrás del cursor se repite con totales revisados; de lo contrario, los totales de un visitante listado permanecen como están listados. Un cursor que no se puede decodificar, o uno de otra lista, devuelve 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>"
}

Autorizaciones

Authorization

string

header

requerido

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 ruta

string

requerido

ID of the analytics project. ID del proyecto de análisis.

Required string length: 1 - 128

Pattern: ^[^\u0000]*$

Cuerpo

application/json

from

string<date-time>

requerido

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.

Ejemplo:

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

string<date-time>

requerido

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.

Ejemplo:

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

event_name

string

Solo incluye eventos con este nombre exacto. Omite para incluir todos los nombres de eventos.

Required string length: 1 - 255

Ejemplo:

"page_view"

filters

object[]

Filtros de propiedades combinados con AND. Un evento debe coincidir con todos los filtros.

Maximum array length: 10

Show child attributes

limit

integer

predeterminado:50

Número máximo de filas en esta página.

Rango requerido: 1 <= x <= 100

cursor

string

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

Respuesta

Éxito

visitors

object[]

requerido

Coincidencia de visitantes, los más recientemente activos primero. Los visitantes con el mismo last_seen se ordenan por distinct_id, en orden descendente.

Show child attributes

next_cursor

string | null

requerido

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.

⌘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

Autorizaciones

Parámetros de ruta

Cuerpo

Respuesta