Skip to main content

Analytics & conversions

Read click analytics for a link or the whole account, stream real-time stats, export raw events, and attribute revenue with conversion tracking. Requires analytics:read (and analytics:write to record conversions).

Code samples use the planned TypeScript SDK interface, which is not published yet; each call maps to a REST endpoint in the API reference.

Timeline plus device / browser / OS / country / referrer breakdowns:

const { data } = await leonai.analytics.link('link_id', { days: 30 });

REST: GET /api/v1/analytics/links/:id (the link id). The analytics API reports trailing windows (a "last N days" window ending now, default 30), so pass days rather than absolute dates. The response has summary, a timeline, and breakdowns for devices, browsers, operating systems, countries, and referrers.

Account-wide analytics & summary​

const account = await leonai.analytics.account({ days: 7 });
const summary = await leonai.analytics.summary(); // dashboard summary

REST: GET /api/v1/analytics/account (accepts days) and GET /api/v1/analytics/summary (last 7/30 days + growth).

Real-time​

Last hour, in 5-minute buckets:

const realtime = await leonai.analytics.realtime('link_id');

REST: GET /api/v1/analytics/realtime/:id.

Raw event export​

CSV; startDate and endDate are required and the range is capped at 1 year:

const eventsCsv = await leonai.analytics.export('link_id', {
  startDate: '2026-06-01T00:00:00Z',
  endDate: '2026-07-01T00:00:00Z',
});

REST: GET /api/v1/analytics/export/:id.

Conversion tracking (Business+)​

Conversion tracking attributes downstream revenue to a specific click.

const { data: link } = await leonai.links.create({
  longUrl: 'https://shop.example.com/checkout',
  conversionTracking: true,
});

Links created with conversionTracking: true append ?lc_id=<clickId> to the destination URL on every redirect.

2. Capture lc_id on your site​

When a visitor lands, read the lc_id query parameter and persist it (cookie, localStorage, or your session) so it survives until checkout:

const params = new URLSearchParams(window.location.search);
const lcId = params.get('lc_id');
if (lcId) localStorage.setItem('leonai_lc_id', lcId);

3. Post the conversion back​

When the visitor converts, send the captured clickId. Requires an API key with the analytics:write scope (this endpoint is API-key only):

await leonai.conversions.track({
  clickId: capturedLcId, // 8–32 chars; or pass linkId to attribute without a click
  name: 'purchase', // required
  value: 49.99,
  currency: 'ILS', // 3 letters; defaults to USD if omitted
  externalId: paymentEvent.id, // idempotency key — safe to retry
});

REST: POST /api/v1/track/conversions. This endpoint is API-key only (JWT is not accepted) and requires the analytics:write scope plus the conversionTracking feature (Business+). Provide at least one of clickId or linkId. externalId makes the call idempotent (a repeat returns 200 instead of 201), so retries never double-count a sale.

4. Read the conversion report​

const report = await leonai.analytics.linkConversions('link_id');
const conversions = await leonai.analytics.conversionsSummary();

REST: GET /api/v1/analytics/:linkId/conversions (per link, includes a daily series) and GET /api/v1/analytics/conversions/summary (account-wide). Both accept optional startDate / endDate (default last 30 days, max 1 year).

  • Links — create links with conversionTracking
  • Webhooks — receive link.clicked events