📋 API: События

Полное описание эндпоинтов для работы с событиями — отправка, получение, поиск и аналитика

💡 Основная концепция: Всё в InstantBase строится вокруг событий. Каждое действие пользователя — это событие, которое вы отправляете в наше API.

Базовый URL

POST https://api.instantbase.online/v1/track

Заголовки

Заголовок Обязательный Описание
X-API-Key ✅ Да Ваш API-ключ (production или test)
Content-Type ✅ Да application/json

Структура события

Обязательные поля

Поле Тип Описание Пример
event string Название события. Используйте понятные имена в snake_case "purchase", "page_view"
user_id или anonymous_id string ID пользователя (авторизованного или анонимного). Должен быть передан хотя бы один "user_12345", "abc123def"

Опциональные поля

Поле Тип Описание Пример
timestamp string (ISO 8601) Время события. Если не указано, используется серверное "2026-03-19T10:30:00Z"
session_id string ID сессии для группировки событий одного визита "sess_abc123"
properties object Параметры события. Любые данные в формате JSON {"page": "/home", "referrer": "google"}
attributes object Атрибуты пользователя, которые нужно сохранить в профиль {"email": "user@example.com", "name": "Иван"}
_metadata object Метаданные для аналитики (см. раздел Метаданные) {"is_order": true, "funnel_sales_step": 1}
app_version string Версия вашего приложения для отслеживания изменений "2.1.0"

Полный пример события

json 
{
  "event": "purchase",
  "user_id": "user_12345",
  "anonymous_id": "abc-123-def",
  "timestamp": "2026-03-19T10:30:00Z",
  "session_id": "sess_789xyz",
  "app_version": "2.1.0",
  "properties": {
    "revenue": 1499.99,
    "order_id": "ORD-2025-001",
    "items": [
      {
        "id": "prod_1",
        "name": "Футболка",
        "price": 1999,
        "quantity": 2
      }
    ]
  },
  "attributes": {
    "email": "user@example.com",
    "name": "Иван Петров",
    "phone": "+79001234567"
  },
  "_metadata": {
    "is_order": true,
    "funnel_sales_step": 4,
    "funnel_sales_name": "Покупка"
  }
}

Эндпоинты для событий

1. Отправка события

POST /v1/track — основной эндпоинт для отправки событий.

Пример с curl

bash 
curl -X POST https://api.instantbase.online/v1/track \
  -H "X-API-Key: ваш_тестовый_ключ" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "test_event",
    "user_id": "test_user_123",
    "properties": {
      "source": "curl",
      "test_property": "Hello World!"
    }
  }'

Успешный ответ (200)

{
  "status": "ok",
  "message": "Event received",
  "queued": true
}

2. Получение ленты событий

GET /api/events/live?limit=20&page=1&search=... — получение событий с пагинацией и поиском.

Параметры запроса

Параметр Описание По умолчанию
limit Количество событий на странице 20
page Номер страницы 1
search Поиск по UID или типу события —

Пример запроса

curl -X GET "https://api.instantbase.online/api/events/live?limit=10&search=user_123" \
  -H "Cookie: session_id=ваша_сессия"

Пример ответа

{
  "events": [
    {
      "id": 12345,
      "occurred_at": "2026-03-19T10:30:00Z",
      "event_name": "purchase",
      "user_id": "user_123",
      "parameters": {
        "revenue": 1499.99,
        "order_id": "ORD-001"
      }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 156,
    "pages": 16
  }
}

3. Получение списка событий

GET /api/events/list — список всех типов событий с количеством.

Пример ответа

{
  "success": true,
  "events": [
    {
      "id": 1,
      "name": "page_view",
      "display_name": "Просмотр страницы",
      "total_events": 15420
    },
    {
      "id": 2,
      "name": "purchase",
      "display_name": "Покупка",
      "total_events": 2341
    }
  ]
}

4. Топ событий за период

GET /api/events/top?from=...&to=...&limit=10 — самые частые события за период.

Параметры запроса

Параметр Описание По умолчанию
from Начальная дата (YYYY-MM-DD) -7 дней
to Конечная дата (YYYY-MM-DD) сегодня
limit Максимум событий 10

Пример ответа

[
  {
    "name": "page_view",
    "display_name": "Просмотр страницы",
    "total_events": 15420,
    "days_active": 7
  },
  {
    "name": "purchase",
    "display_name": "Покупка",
    "total_events": 2341,
    "days_active": 7
  }
]

5. Получение сырого события

GET /api/raw-events?event_id=123 — получение исходных данных события (полезно для отладки).

Пример ответа

{
  "success": true,
  "event_id": 12345,
  "raw_data": {
    "event": "purchase",
    "user_id": "user_123",
    "properties": {
      "revenue": 1499.99
    },
    "auth": {
      "company_id": 42,
      "app_id": 13
    }
  }
}

Идентификация пользователей

user_id vs anonymous_id

Поле Когда использовать Пример
user_id Пользователь авторизован в вашей системе ID из вашей БД, email, username
anonymous_id Пользователь не авторизован (гость) Cookie, device ID, fingerprint
💡 Склейка профилей: Если вы сначала отправляли события с anonymous_id, а потом пользователь авторизовался, отправляйте события с обоими полями — система автоматически свяжет анонимный профиль с авторизованным.

Пример склейки

// Анонимные действия
{
  "event": "page_view",
  "anonymous_id": "abc123",
  "properties": {
    "page": "/home"
  }
}

// После авторизации
{
  "event": "purchase",
  "user_id": "user_123",
  "anonymous_id": "abc123",
  "properties": {
    "revenue": 1499.99
  }
}

Работа с сессиями

Поле session_id позволяет группировать события одного визита пользователя. Это полезно для анализа пути пользователя и воронок.

{
  "event": "page_view",
  "user_id": "user_123",
  "session_id": "sess_abc123",
  "timestamp": "2026-03-19T10:30:00Z"
}

Рекомендации по формированию session_id:

Свойства событий (properties)

Поле properties может содержать любые данные в формате JSON. Рекомендуется передавать все важные параметры события.

Рекомендованные свойства для стандартных событий

Событие Рекомендованные свойства
page_view page, title, referrer, url
purchase order_id, revenue, items, currency
signup method, source
add_to_cart product_id, price, quantity

Атрибуты пользователя (attributes)

Поле attributes используется для сохранения или обновления профиля пользователя. Атрибуты сохраняются в профиле и доступны в разделе "Клиенты".

Примеры атрибутов

{
  "event": "signup",
  "user_id": "user_123",
  "attributes": {
    "email": "user@example.com",
    "name": "Иван Петров",
    "phone": "+79001234567",
    "birth_date": "1990-01-01",
    "city": "Москва",
    "subscription_plan": "premium"
  }
}

Метаданные (_metadata)

Метаданные используются для обогащения событий бизнес-логикой. Подробнее в разделе Метаданные.

Основные метаданные

Акроним Описание Пример
is_order Помечает событие как заказ true
is_activation Помечает событие как активацию true
funnel_sales_step Номер шага в воронке продаж 1, 2, 3
funnel_sales_name Название шага в воронке "Просмотр товара"
event_display_name Отображаемое имя события "Покупка"
event_color Цвет события на графиках "#FF5733"

Коды ответов и ошибки

Код Описание Решение
200 Успешно Событие принято и поставлено в очередь
400 Неверный JSON Проверьте синтаксис JSON
400 Missing required field: event Добавьте поле event
400 Either user_id or anonymous_id is required Добавьте user_id или anonymous_id
401 Invalid or missing API key Проверьте ключ в заголовке X-API-Key
429 Too many requests Превышен rate limit, подождите
500 Internal server error Повторите запрос позже

Лимиты и квоты

Тип лимита Production Test
Событий в месяц Зависит от тарифа 50 000
Rate limit (запросов/минуту) 1000 200
Размер события 1 МБ 1 МБ

Рекомендации по использованию

  • Именование событий: используйте snake_case (например, page_view, add_to_cart)
  • Не передавайте чувствительные данные: пароли, номера карт, персональные данные
  • Используйте тестовые ключи на этапе разработки
  • Группируйте события сессией для анализа пути пользователя
  • Передавайте все важные параметры — это поможет в будущем анализе
  • Для покупок обязательно передавайте revenue и метаданные "is_order": true

Примеры интеграции

JavaScript (браузер)

async function trackEvent(eventName, userId, properties = {}) {
  try {
    const response = await fetch('https://api.instantbase.online/v1/track', {
      method: 'POST',
      headers: {
        'X-API-Key': 'ваш_тестовый_ключ',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        event: eventName,
        user_id: userId,
        properties: properties,
        timestamp: new Date().toISOString()
      })
    });
    
    return await response.json();
  } catch (error) {
    console.error('Failed to track event:', error);
  }
}

Node.js

const axios = require('axios');

async function trackEvent(event, userId, properties = {}) {
  try {
    const response = await axios.post('https://api.instantbase.online/v1/track', {
      event,
      user_id: userId,
      properties,
      timestamp: new Date().toISOString()
    }, {
      headers: {
        'X-API-Key': process.env.INSTANTBASE_API_KEY
      }
    });
    
    return response.data;
  } catch (error) {
    console.error('Failed to track event:', error.response?.data || error.message);
  }
}

Python

import requests
import os
from datetime import datetime

API_KEY = os.environ.get('INSTANTBASE_API_KEY')

def track_event(event, user_id, properties=None):
    url = 'https://api.instantbase.online/v1/track'
    headers = {
        'X-API-Key': API_KEY,
        'Content-Type': 'application/json'
    }
    data = {
        'event': event,
        'user_id': user_id,
        'properties': properties or {},
        'timestamp': datetime.now().isoformat()
    }
    
    response = requests.post(url, json=data, headers=headers)
    return response.json()

Что дальше?

👥 Клиенты

Работа с профилями и атрибутами пользователей

Перейти →

📌 Метаданные

Настройка метаданных для событий

Перейти →

Остались вопросы по API?

Напишите нам, и мы поможем с интеграцией

support@instantbase.online Telegram