[Docs](https://linkinseconds.com/docs)Developers

# Analytics API

GET /api/v1/links/{slug}/analytics and GET /api/v1/analytics return the dashboard's report as JSON: views, time, read-through, audience, timing.

Two read-only endpoints return the same report the dashboard's Analytics pages render, as JSON: one for a single link and one for the whole account. Both are computed by the same engine as the dashboard, so a number here never differs from what you see on the site. They work on every plan, Free included.

## Analytics for one link

GET`/api/v1/links/{slug}/analytics`API key required

`{slug}` is the last part of the public link, for example `q3-summary` in `lisview.com/q3-summary`. The link must belong to the key's owner.

Query parameters

`range`string

One of `7d`, `14d`, `30d`, `90d` or `all`. Default `30d`. Ranges are whole UTC days ending today; `all` runs from the link's creation.

```
curl "https://linkinseconds.com/api/v1/links/q3-summary/analytics?range=30d" \
  -H "Authorization: Bearer $LIS_API_KEY"
```

200 OK (abridged)

```
{
  "link": { "slug": "q3-summary", "title": "Q3 summary", "url": "https://lisview.com/q3-summary", "kind": "pdf" },
  "range": { "key": "30d", "from": "2026-09-05T00:00:00.000Z", "to": "2026-10-05T00:00:00.000Z", "days": 30, "label": "Last 30 days" },
  "totals": {
    "views": 128, "uniques": 96, "sessions": 74,
    "avgEngagedMs": 102000, "medianEngagedMs": 61000, "totalEngagedMs": 7548000,
    "completionPct": 58, "downloads": 12, "qrScans": 9,
    "returningPct": 18.9, "bouncePct": 21.6, "botsExcluded": 7, "atypical": 3
  },
  "previous": { "views": 91, "uniques": 70, "avgEngagedMs": 88000, "downloads": 4, "sessions": 52 },
  "deltas": {
    "views": { "pct": 41, "dir": "up" },
    "uniques": { "pct": 37, "dir": "up" },
    "avgEngagedMs": { "pct": 16, "dir": "up" },
    "downloads": { "pct": 50, "dir": "up" }
  },
  "granularity": "day",
  "series": [
    { "date": "2026-09-05", "label": "Sep 5", "views": 3, "uniques": 3, "avgEngagedS": 74 }
  ],
  "breakdowns": {
    "countries": [{ "key": "IN", "count": 69, "pct": 53.9 }, { "key": "US", "count": 27, "pct": 21.1 }],
    "cities": [{ "key": "Surat, IN", "count": 31, "pct": 24.2 }],
    "referrers": [{ "key": "Direct", "count": 90, "pct": 70.3 }, { "key": "linkedin.com", "count": 22, "pct": 17.2 }],
    "sources": [{ "key": "Direct", "count": 90, "pct": 70.3 }, { "key": "Referral", "count": 29, "pct": 22.7 }, { "key": "QR scan", "count": 9, "pct": 7 }],
    "devices": [{ "key": "Mobile", "count": 79, "pct": 61.7 }, { "key": "Desktop", "count": 49, "pct": 38.3 }],
    "browsers": [{ "key": "Safari", "count": 41, "pct": 55.4 }],
    "os": [{ "key": "iOS", "count": 38, "pct": 51.4 }],
    "screens": [{ "key": "360-479", "count": 40, "pct": 54.1 }]
  },
  "timing": { "byHour": [0, 1, 2], "byWeekday": [9, 24, 31, 22, 20, 15, 7], "heat": [[0]], "peakHour": 14, "peakWeekday": 2 },
  "content": {
    "kind": "pages", "pagesTotal": 12, "avgPagesSeen": 6.9, "readToEndPct": 23,
    "pages": [{ "page": 1, "views": 74, "reachPct": 100, "avgMs": 9000, "attentionPct": 8.8 }],
    "dropoff": { "afterPage": 6, "lostPct": 34 }
  },
  "insights": [
    { "id": "attention", "label": "Average attention", "value": "1m 42s", "detail": "median 1m 1s across 74 opens", "tone": "good" }
  ],
  "recent": [
    {
      "at": "2026-10-04T13:12:44.120Z", "country": "IN", "city": "Surat",
      "device": "Mobile", "browser": "Safari", "os": "iOS", "source": "Direct",
      "engagedMs": 95000, "progress": "7 of 12 pages", "downloaded": false, "returning": false, "atypical": false
    }
  ]
}
```

### Reading the report

| Field | Meaning |

| `range` | UTC. `to` is exclusive (the start of tomorrow). `days` is the width. |

| `totals` | Views come from the view log and cover every open; sessions and everything about time or progress come from the engagement tracker, so sessions can be lower than views. downloads is all-time. `atypical` counts sessions from a bot, an email scanner or a link preview (engaged under 1 s and gone within 2 s): they are not in `sessions` and move no average. A bot session is also in `botsExcluded`. |

| `previous` | The same width of time immediately before the range, for the deltas. |

| `deltas` | Signed percent change vs `previous`. `pct` is `null` when the previous period was zero. |

| `series` | One point per day, or per week when `granularity` is `week` (ranges over 120 days). |

| `breakdowns` | Top 8 buckets each, with `pct` as the share of the card's total. Countries are ISO 3166-1 alpha-2 codes. |

| `timing` | Counts by UTC hour (0 to 23) and weekday (0 = Sunday), plus `heat[weekday][hour]`. |

| `content` | `kind` is `pages` (PDF), `media` (video, audio), `scroll` (web pages, images, text, documents) or `none` (archives). Only the matching sub-object is present. `pages` carries `dropoff` (`afterPage`, `lostPct`: the page after which the largest share of readers stopped) and `media` carries `media.dropoff` (`beforePct` of 25, 50, 75 or 100, `lostPct`). Both are `null` until at least 3 sessions and a loss of at least 10 points. |

| `insights` | The same cards the dashboard shows, already phrased. tone is good, neutral or warn. |

| `recent` | Up to 25 most recent opens that have engagement data, newest first. Each carries the time, country and city, device, browser and OS, how far the viewer got, and `atypical` (true for a bot, scanner or preview open, which is listed but in no average). No names, emails or IP addresses. |

## Analytics for the whole account

GET`/api/v1/analytics`API key required

Every link the key's owner has, as one report, plus a leaderboard and the file-kind mix. Album and website pages are not included; their member files are.

Query parameters

`range`string

Same values and default as above. `all` runs from your oldest link.

Shell

```
curl "https://linkinseconds.com/api/v1/analytics?range=7d" \
  -H "Authorization: Bearer $LIS_API_KEY"
```

200 OK (abridged)

```
{
  "range": { "key": "7d", "from": "2026-09-28T00:00:00.000Z", "to": "2026-10-05T00:00:00.000Z", "days": 7, "label": "Last 7 days" },
  "totals": { "views": 412, "uniques": 301, "sessions": 240, "avgEngagedMs": 64000, "completionPct": null, "downloads": 58, "botsExcluded": 19, "atypical": 11 },
  "previous": { "views": 380, "uniques": 270, "avgEngagedMs": 60000, "downloads": 11, "sessions": 210 },
  "deltas": { "views": { "pct": 8, "dir": "up" }, "uniques": { "pct": 11, "dir": "up" }, "avgEngagedMs": { "pct": 7, "dir": "up" }, "downloads": { "pct": 9, "dir": "up" } },
  "granularity": "day",
  "series": [ { "date": "2026-09-28", "label": "Sep 28", "views": 51, "uniques": 40, "avgEngagedS": 58 } ],
  "breakdowns": { "countries": [], "cities": [], "referrers": [], "sources": [], "devices": [], "browsers": [], "os": [], "screens": [] },
  "timing": { "byHour": [], "byWeekday": [], "heat": [], "peakHour": 10, "peakWeekday": 3 },
  "insights": [],
  "top_links": [
    {
      "id": "6f1c…", "slug": "q3-summary", "title": "Q3 summary", "kind": "pdf",
      "views": 128, "uniques": 96, "avgEngagedMs": 102000, "completionPct": 58, "downloads": 12,
      "spark": [3, 5, 2, 9, 11, 4, 6]
    }
  ],
  "mix": [{ "key": "PDF", "count": 260, "pct": 63.1 }, { "key": "Images", "count": 152, "pct": 36.9 }],
  "all_time": { "views": 9120, "downloads": 1033, "links": 42 },
  "truncated": false
}
```

`top_links` holds at most 25 rows, most viewed first, each with a `spark` of daily views (oldest first, up to 30 days). `mix` is views by file kind. `all_time` comes from the link rows and ignores the range. The account report has no `content` or `recent` block; ask a single link for those. `truncated` (on both endpoints) is `true` when a very busy window hit the row cap: the newest views were counted and some older ones in the range were not, so totals and deltas are lower bounds. Ask for a shorter range for exact numbers.

## Errors

| Status | code | What happened |

| 400 | `bad_range` | range is not one of `7d`, `14d`, `30d`, `90d`, `all`. |

| 401 | `unauthorized` | Missing, malformed or revoked API key. |

| 403 | `banned` | The account is suspended. |

| 404 | `not_found` | No link with that slug belongs to this account (link endpoint only). |

| 429 | `rate_limited` | Over this key's rate limit. Wait `Retry-After` seconds. |

See [Errors and limits](https://linkinseconds.com/docs/api/errors) for the shared conventions. Responses are sent with `Cache-Control: no-store` (so no browser or proxy keeps a copy) and the usual CORS headers, so a browser dashboard can call them directly with a key you control.

Each analytics call costs 5 units of your key's [rate limit](https://linkinseconds.com/docs/api/errors). Reports are cached for 60 seconds per account, link and range, so polling faster than once a minute returns the same numbers.

How the numbers are made

Views count every page load (also with JavaScript off). Time, pages, watch-through and scroll depth come from a cookieless per-page-load session that only counts time while the tab is visible. Bots and link previews are removed from everything and reported in `totals.botsExcluded`. Atypical sessions (a bot, or an email scanner or link preview that rendered the page for under a second) are counted in `totals.atypical`, flagged in `recent` and kept out of every average. Opens recorded before engagement tracking launched have views but no time data, so `sessions` can be lower than `views`. Details in [Views and analytics](https://linkinseconds.com/docs/analytics).

[PreviousList links](https://linkinseconds.com/docs/api/links)[Next Errors and limits](https://linkinseconds.com/docs/api/errors)

Last updated 4 October 2026. Something unclear or missing? [Tell us](https://linkinseconds.com/contact).

Source: https://linkinseconds.com/docs/api/analytics
