На этой странице

Партнёрская аналитика

Эндпоинт для скриптов и мониторинга: отдаёт те же цифры, что страница «Аналитика трафика» в кабинете партнёра. Один GET-запрос с ключом — и видно, сколько человек пришло по вашей ссылке, кто реально пользуется сервисом, сколько запросов и токенов они принесли.

Доступ и данные

Эндпоинт работает по тому же ключу, что и остальной API: Authorization: Bearer srz_live_…. Ключ привязан к аккаунту, поэтому данные всегда только ваши — чужие приглашённые через него не видны. Вход через Logto-сессию не нужен: запрос можно слать с сервера по расписанию.

Ключ создаётся в разделе «API-ключи» кабинета. Если ключа нет, вернётся 401 с заголовком WWW-Authenticate: Bearer.

GET/api/v1/partner?method=summary&period=30
bash
curl -sS "https://srezai.ru/api/v1/partner?method=summary&period=30" \
  -H "Authorization: Bearer $SREZAI_API_KEY"

Методы

Метод задаётся параметром method. Формат ответа у всех методов общий — меняется только набор полей, чтобы мониторинг не тащил сотни строк пользователей, а скрипт с деталями получал их отдельно.

summaryпо умолчаниюнеобязательный

Сводка за период: приглашённые, активные, запросы, успешность, токены, списания, статусы, последняя активность и топ-5 инструментов. Самый лёгкий вариант для cron-проверки.

trafficграфикнеобязательный

Сводка и статусы плюс series (запросы и токены по дням) и tools (разбивка по инструментам за период).

usersсписокнеобязательный

Сводка и статусы плюс страница приглашённых: поиск, фильтр по статусу, сортировка и пагинация. По умолчанию 100 человек на страницу.

allвсё сразунеобязательный

Сводка, статусы, топ-инструменты, график и страница пользователей. По умолчанию 50 пользователей на страницу, остальное — через offset.

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

methodstringнеобязательный

summary, traffic, users или all. По умолчанию summary. Неизвестное значение — 400.

period7 | 30 | 90необязательный

Окно аналитики в днях. По умолчанию 30. Влияет на сводку, график и метрики пользователей; статусы всегда считаются по последним 90 дням.

statusstringнеобязательный

Только для users и all: active (были запросы за 7 дней), quiet (за 30, но не за 7), lapsed (за 90, но не за 30), never (ни одного запроса за 90 дней) или all.

sortstringнеобязательный

Только для списка: requests (по умолчанию), tokens, spent, activity, created, name.

orderasc | descнеобязательный

Направление сортировки, по умолчанию desc. Для name удобнее asc.

limit1–500необязательный

Размер страницы пользователей. По умолчанию 100 для users и 50 для all; для остальных методов список не отдаётся. Максимум 500.

offset0–10000необязательный

Сдвиг страницы. Вместе с hasMore позволяет обойти всех приглашённых.

qstringнеобязательный

Поиск по имени, маскированному адресу, тарифу и стране. До 100 символов.

Метод summary

Самый дешёвый по объёму ответ: его удобно сверять в ежедневном отчёте и отправлять в Telegram, если что-то изменилось.

json
{
  "ok": true,
  "method": "summary",
  "generatedAt": "2026-10-23T10:30:00.000Z",
  "period": { "days": 30, "from": "2026-09-24", "to": "2026-10-23" },
  "referral": {
    "code": "87g9uzbp",
    "link": "https://srezai.ru/?ref=87g9uzbp"
  },
  "summary": {
    "invited": 12,
    "activeUsers": 7,
    "activeShare": 58.3,
    "requests": 412,
    "successfulRequests": 398,
    "successRate": 96.6,
    "avgRequestsPerActiveUser": 58.9,
    "tokensIn": 18400,
    "tokensOut": 512000,
    "tokens": 530400,
    "spentKopecks": 6200,
    "spentRub": 62
  },
  "statuses": { "active": 3, "quiet": 4, "lapsed": 2, "never": 3 },
  "lastActivityAt": "2026-10-23T09:58:12.000Z",
  "topTools": [
    { "key": "web-search", "label": "Web-Search", "requests": 227, "tokens": 142000, "users": 7, "share": 55.1 },
    { "key": "read-page", "label": "Read", "requests": 104, "tokens": 210400, "users": 6, "share": 25.2 },
    { "key": "deep-search", "label": "DeepSearch", "requests": 51, "tokens": 132000, "users": 4, "share": 12.4 }
  ],
  "privacy": "Только агрегаты и маскированные адреса; поисковые запросы, Telegram и IP приглашённых не отдаются.",
  "docs": "https://srezai.ru/docs/partner"
}

Что означают поля

  • summary.invited — сколько человек зарегистрировались по вашей ссылке за всё время.
  • summary.activeUsers и activeShare — сколько из них реально пользуются сервисом в выбранном окне и какая это доля.
  • summary.requests, successfulRequests, successRate — интенсивность и качество работы приглашённых.
  • summary.tokensIn, tokensOut, tokens — сколько трафика они прокачали.
  • summary.spentKopecks и spentRub — сколько денег принесли их запросы.
  • statuses — распределение по активности: активные, затихшие, выпавшие и те, кто так и не начал.
  • lastActivityAt — последний запрос за 90 дней среди всех приглашённых; удобный сигнал «рефералы вообще живые?».
  • topTools — пять инструментов, которыми пользуются чаще всего. Если у приглашённых только Web-Search, значит остальные возможности они ещё не освоили.

Метод traffic

Для графика и разбора «когда и чем»: те же итоги плюс точки по дням и полная разбивка по инструментам за период.

json
{
  "ok": true,
  "method": "traffic",
  "period": { "days": 7, "from": "2026-10-17", "to": "2026-10-23" },
  "summary": { "invited": 12, "activeUsers": 4, "requests": 96, "...": "..." },
  "statuses": { "active": 3, "quiet": 4, "lapsed": 2, "never": 3 },
  "tools": [
    { "key": "web-search", "label": "Web-Search", "requests": 58, "tokens": 37000, "users": 4, "share": 60.4 }
  ],
  "series": [
    { "date": "2026-10-17", "label": "17 окт", "requests": 9, "successfulRequests": 9, "tokensIn": 400, "tokensOut": 9000 },
    { "date": "2026-10-18", "label": "18 окт", "requests": 14, "successfulRequests": 13, "tokensIn": 600, "tokensOut": 14300 },
    { "date": "2026-10-19", "label": "19 окт", "requests": 0, "successfulRequests": 0, "tokensIn": 0, "tokensOut": 0 }
  ]
}

series содержит ровно period точек, последняя — сегодня (дни считаются по Москве). tools[].share — доля запросов инструмента от всех запросов периода; tools[].users — сколько разных людей им пользовались.

Метод users

Список приглашённых для детального разбора. Адрес приходит маскированным, полный email не отдаётся даже в JSON.

json
{
  "ok": true,
  "method": "users",
  "period": { "days": 30, "from": "2026-09-24", "to": "2026-10-23" },
  "statuses": { "active": 3, "quiet": 4, "lapsed": 2, "never": 3 },
  "users": {
    "total": 12,
    "limit": 2,
    "offset": 0,
    "hasMore": true,
    "items": [
      {
        "id": "u123",
        "name": "Анна",
        "email": "a***@yandex.ru",
        "plan": "free",
        "country": "RU",
        "createdAt": "2026-09-12T08:15:00.000Z",
        "lastSeenAt": "2026-10-23T09:58:00.000Z",
        "lastActivityAt": "2026-10-23T09:58:12.000Z",
        "status": "active",
        "requests": 128,
        "successfulRequests": 124,
        "successRate": 96.9,
        "activeDays": 11,
        "tokensIn": 4200,
        "tokensOut": 98000,
        "tokens": 102200,
        "spentKopecks": 1500,
        "spentRub": 15,
        "tools": [
          { "key": "web-search", "label": "Web-Search", "requests": 90 },
          { "key": "read-page", "label": "Read", "requests": 38 }
        ]
      },
      {
        "id": "u456",
        "name": "Иван",
        "email": "i***@gmail.com",
        "plan": "pro",
        "country": "KZ",
        "createdAt": "2026-08-30T11:02:00.000Z",
        "lastSeenAt": "2026-10-18T12:40:00.000Z",
        "lastActivityAt": "2026-10-18T12:40:33.000Z",
        "status": "quiet",
        "requests": 24,
        "successfulRequests": 24,
        "successRate": 100,
        "activeDays": 5,
        "tokensIn": 900,
        "tokensOut": 21000,
        "tokens": 21900,
        "spentKopecks": 240,
        "spentRub": 2.4,
        "tools": [
          { "key": "deep-search", "label": "DeepSearch", "requests": 24 }
        ]
      }
    ]
  }
}

Поле id — стабильный идентификатор строки для дедупликации между запусками скрипта; это не Logto-sub и не публичный идентификатор. Следующая страница:

text
?method=users&period=30&status=active&sort=requests&order=desc&limit=100&offset=100

Скрипт мониторинга

Минимальный ежедневный отчёт: сколько приглашённых активны, сколько запросов они сделали и не пора ли напомнить о сервисе тем, кто затих.

python
import json
import os
import urllib.request

KEY = os.environ["SREZAI_API_KEY"]
url = "https://srezai.ru/api/v1/partner?method=summary&period=7"
req = urllib.request.Request(url, headers={"Authorization": f"Bearer {KEY}"})

with urllib.request.urlopen(req, timeout=30) as resp:
    data = json.load(resp)

s = data["summary"]
print(f"Приглашено: {s['invited']}")
print(f"Активны за 7 дней: {s['activeUsers']} ({s['activeShare']}%)")
print(f"Запросы: {s['requests']}, успешных: {s['successRate']}%")
print(f"Токены: {s['tokens']}, списано: {s['spentRub']} ₽")
print("Без запросов за 90 дней:", data["statuses"]["never"])

Лимиты и стоимость

Запросы к партнёрской аналитике не списывают деньги и не тратят суточную квоту поиска: это чтение уже оплаченных данных. Но у эндпоинта своя защита от флуда, чтобы один ключ не вычитывал базу бесконечно:

burst30 в минутунеобязательный

Не больше 30 запросов в минуту на аккаунт. При превышении — 429 с reason: "burst" и Retry-After.

quota5 000 в суткинеобязательный

Суточный потолок аналитики. При исчерпании — 429 с reason: "quota".

headersX-RateLimit-*необязательный

В каждом ответе есть X-RateLimit-Limit, Remaining и Reset — по ним скрипт может планировать следующий запуск.

json
{
  "error": "Слишком много запросов к партнёрской аналитике. Повторите через 42 с — поисковую квоту такой отказ не расходует.",
  "code": "rate_limited",
  "reason": "burst",
  "retryAfterSec": 42
}

Ошибки

  • 400 — неизвестный method/period, неверный status, limit или offset. В теле будет code: "bad_request" и подсказка, какие значения допустимы.
  • 401 — ключ отсутствует, отозван или неверен.
  • 429 — сработал лимит аналитики; повторите после Retry-After.
  • 503 — недоступна база. Это наша авария; в ответе code: "service_unavailable", повторите позже.

Приватность

API возвращает только то, что разрешено показывать пригласившему: агрегаты, имя, маскированный адрес, тариф, страну и служебные даты. Поисковые запросы приглашённых, их Telegram, IP и полные контакты не отдаются ни в одном методе — это тот же контракт, что у страницы «Аналитика трафика».