Monthly Reports

Retrieve the same monthly report LinkForty emails on the 1st of each month, as data.

Overview

A monthly report is a single object covering one calendar month for your workspace: clicks with month-over-month change, a daily series, top links with share, sources, countries and devices, app installs and attribution, events and revenue, and the sentences and recommended actions the email shows. It is available on every plan — the dashboard's analytics windows are limited by your plan, the monthly report is not.

A month that has ended is generated once and stored. The stored copy is exactly what was emailed; requesting it again returns the same data. The current month is built on request from live data and is not stored.

List Available Months

GET /api/reports/monthly

Authentication

Requires a valid JWT or API key. See Authentication.

Response

{
  "reports": [
    { "period": "2026-09", "label": "September 2026", "generatedAt": null, "live": true },
    { "period": "2026-08", "label": "August 2026", "generatedAt": "2026-09-01T13:00:05.000Z", "live": false }
  ]
}

live: true marks the current month. Months appear in the list once a report has been generated for them — by the monthly email, or by the first request to the endpoint below.

Get a Month's Report

GET /api/reports/monthly/:period

Path Parameters

Parameter	Type	Description
period	string	The month as YYYY-MM, e.g. 2026-08

Query Parameters

Parameter	Type	Required	Description
regenerate	1	No	Rebuild a finished month from current data, replacing the stored copy. Workspace owners only. Use it when events arrived after the 1st.

Response

The report object. Sections that depend on a data stream are null when the workspace has never had that stream (installs without the SDK, pixel without the website pixel, events without either), and present with zeros when it has but the month was quiet.

{
  "organization": { "id": "…", "name": "Trailhead Coffee", "slug": "trailhead-coffee", "tier": "pro" },
  "period": { "type": "monthly", "start": "2026-08-01", "end": "2026-09-01", "label": "August 2026", "priorLabel": "last month" },
  "kpis": {
    "clicks": { "value": 22140, "prior": 15940, "deltaPct": 39 },
    "uniques": { "value": 12310, "prior": 11402, "deltaPct": 8 },
    "installs": { "value": 884, "prior": 703, "deltaPct": 26 },
    "sessions": null
  },
  "daily": [{ "day": "2026-08-01", "clicks": 512 }, "…"],
  "bestDay": { "day": "2026-08-19", "clicks": 1821 },
  "topLinks": [{ "label": "Fall Roast Launch", "sublabel": "/fallroast", "value": 6912, "share": 0.31 }, "…"],
  "otherLinks": { "count": 6, "clicks": 6126 },
  "zeroClickLinks": 2,
  "sources": [{ "label": "Instagram", "value": 10184, "share": 0.46 }, "…"],
  "countries": [{ "label": "United States", "value": 17269, "share": 0.78 }, "…"],
  "devices": [{ "label": "mobile", "value": 17933, "share": 0.81 }, "…"],
  "installs": { "byPlatform": [{ "label": "ios", "value": 541, "share": 0.61 }, "…"], "attributed": 389, "attributionRate": 0.44 },
  "pixel": null,
  "events": {
    "total": { "value": 7412, "prior": 6030, "deltaPct": 23 },
    "byName": [{ "label": "screen_view", "sublabel": "app", "value": 5980, "share": 0.81 }, "…"],
    "revenue": [{ "currency": "USD", "amount": 18402.5, "prior": 14190 }],
    "conversions": null,
    "perInstall": 8.38
  },
  "housekeeping": { "linksCreated": ["Fall Roast Launch", "…"], "linksExpired": ["Summer Cold Brew"], "linksDisabled": 0, "linksWithStoreUrls": 3 },
  "insights": {
    "headline": "Clicks up 39% on last month — 22,140 this month.",
    "links": "Two links carry 52% of your traffic: Fall Roast Launch and App Download — Instagram bio.",
    "events": "$18,402.50 in tracked revenue across 7,412 events.",
    "actions": [{ "title": "Enable app-token attribution", "body": "…" }]
  },
  "generatedAt": "2026-09-01T13:00:05.000Z"
}

kpis.uniques is null when your plan's raw click history no longer reaches back to the start of the month — unique visitors cannot be reconstructed after that, so the report omits them rather than guess.

Errors

Status	error	When
400	INVALID_PERIOD	period is not YYYY-MM
400	PERIOD_IN_FUTURE	The month has not started
400	PERIOD_LIVE	regenerate=1 on the current month
403	INSUFFICIENT_ROLE	regenerate=1 by a non-owner
404	PERIOD_BEFORE_WORKSPACE	The month ended before the workspace was created
404	PERIOD_NOT_RETAINED	More than 400 days ago