# Analytics & conversions

Source: https://developers.leonai.io/docs/guides/analytics/

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](https://developers.leonai.io/docs/sdks/) interface, which is not published
yet; each call maps to a REST endpoint in the [API reference](https://developers.leonai.io/docs/api-reference/).

## Per-link analytics

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

```ts
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

```ts
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:

```ts
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:

```ts
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.

### 1. Create a link with tracking on

```ts
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:

```ts
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):

```ts
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

```ts
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).

## Related

- [Links](https://developers.leonai.io/docs/guides/links/) — create links with `conversionTracking`
- [Webhooks](https://developers.leonai.io/docs/guides/webhooks/) — receive `link.clicked` events