# Tracked links

> Read your tracked WhatsApp links and their click stats, and understand how each lead gets its source and its link.

Source: https://docs.whatsetter.com/developers/guides/links/

A tracked link is a short WhatSetter address (`https://app.whatsetter.com/l/insta-bio`) that opens a WhatsApp conversation with one of your agents and records the click. The API exposes your links and their stats read-only; you create and edit them in the dashboard.

## Endpoints

| Method | Path | Scope |
|---|---|---|
| GET | [`/links`](/api-reference/operations/listlinks/) | `links:read` |
| GET | [`/links/{id}`](/api-reference/operations/getlink/) | `links:read` |

## List links

**cURL**

```bash
curl "https://app.whatsetter.com/api/v1/links?status=active&limit=25" \
  -H "Authorization: Bearer ws_live_…"
```

**JavaScript**

```js
const res = await fetch('https://app.whatsetter.com/api/v1/links?status=active&limit=25', {
  headers: { Authorization: 'Bearer ws_live_…' },
});
const { data: links, pagination } = await res.json();
```

**Python**

```python
import requests

r = requests.get(
    "https://app.whatsetter.com/api/v1/links",
    params={"status": "active", "limit": 25},
    headers={"Authorization": "Bearer ws_live_…"},
)
links = r.json()["data"]
```

```json
{
  "data": [
    {
      "id": "66f1a2b3c4d5e6f7a8b9c0f1",
      "slug": "insta-bio",
      "name": "Instagram bio",
      "url": "https://app.whatsetter.com/l/insta-bio",
      "campaign_id": "acme-france-1-ab12",
      "status": "active",
      "channel": "auto",
      "clicks": 128,
      "last_click_at": "2026-09-18T10:00:00.000Z",
      "created_at": "2026-09-01T08:00:00.000Z"
    }
  ],
  "pagination": { "has_more": false, "next_cursor": null }
}
```

| Parameter | What it does |
|---|---|
| `campaign_id` | The campaign's slug or its `id`. |
| `status` | `active` or `inactive`. |
| `limit`, `cursor` | Pagination. |

| Field | Meaning |
|---|---|
| `url` | The address to share. |
| `campaign_id` | The campaign (and so the WhatsApp number) the link opens. |
| `channel` | `auto` when the platform is read on each click, or a forced platform. |
| `clicks` | Total clicks since creation. Preview robots and crawlers are not counted. |

## Get one link with its 30-day stats

**cURL**

```bash
curl "https://app.whatsetter.com/api/v1/links/66f1a2b3c4d5e6f7a8b9c0f1" \
  -H "Authorization: Bearer ws_live_…"
```

**JavaScript**

```js
const res = await fetch('https://app.whatsetter.com/api/v1/links/66f1a2b3c4d5e6f7a8b9c0f1', {
  headers: { Authorization: 'Bearer ws_live_…' },
});
const { data: link } = await res.json();
```

**Python**

```python
import requests

r = requests.get(
    "https://app.whatsetter.com/api/v1/links/66f1a2b3c4d5e6f7a8b9c0f1",
    headers={"Authorization": "Bearer ws_live_…"},
)
link = r.json()["data"]
```

```json
{
  "data": {
    "id": "66f1a2b3c4d5e6f7a8b9c0f1",
    "slug": "insta-bio",
    "name": "Instagram bio",
    "url": "https://app.whatsetter.com/l/insta-bio",
    "campaign_id": "acme-france-1-ab12",
    "status": "active",
    "channel": "auto",
    "clicks": 128,
    "last_click_at": "2026-09-18T10:00:00.000Z",
    "created_at": "2026-09-01T08:00:00.000Z",
    "stats_30d": {
      "clicks": 128,
      "by_channel": { "instagram": 90, "tiktok": 30, "direct": 8 },
      "leads": 41,
      "qualified": 12
    }
  }
}
```

`stats_30d` holds the same numbers as the link's drawer in the dashboard: clicks over the last 30 days, split by the platform read on each click, plus the conversations the link brought and how many of them were qualified.

## How attribution works

The platform is read **at click time**, never guessed from the message: the app the link was opened from (Instagram, TikTok, LinkedIn…), the referrer, or the variant of the link you shared (`?c=qr`, `?c=email`, `?c=sms` for silent supports), otherwise `direct`. When the person then writes to the number, WhatSetter looks at the clicks on that number's links in the last 45 minutes. One click, or clicks from a single platform, gives a **certain** attribution; several platforms in the window gives the most recent click from the person's country, marked **probable**. A message carrying a Meta ad signal is attributed to the ad, certain, without any link. No click at all means the person wrote spontaneously: `inbound`.

Each lead then carries `source` (the platform), `tracked_link_id` (this link's `id`) and `source_confidence` (`certain` or `probable`). Filter them with [`GET /leads?tracked_link_id=`](/developers/guides/leads/) or `?source=instagram`.

## Errors you will meet

| HTTP | `code` | When |
|---|---|---|
| 401 | `missing_api_key`, `invalid_api_key` | Key absent, unknown or revoked. |
| 403 | `insufficient_scope` | The key lacks `links:read`. |
| 404 | `not_found` | Unknown link, or a link of another workspace. |
| 422 | `validation_error` | Unknown `status`, invalid cursor. |
| 429 | `rate_limited` | Too many requests this minute. Honor `Retry-After`. |

## Related

- [Leads: filter by source and link](/developers/guides/leads/)
- [Campaigns](/developers/guides/campaigns/)
- [Tracked links in the dashboard](/dashboard/tracked-links/)
