# List links

`GET https://app.clik.so/api/links`

> **In short:** Returns a page of your workspace's links, newest first. Filter by folder, status, tag or a search term, and page through with `limit` and `offset`.

## You need

* **API key permission:** `read`
* **Workspace role:** viewer or higher
* **Plan:** any plan, including Free

## Example

```bash
curl "https://app.clik.so/api/links?limit=20" \
  -H "Authorization: Bearer $CLIKSO_API_KEY"
```

Response 200:

```json
{
  "status": 200,
  "success": true,
  "message": "Success",
  "data": [
    {
      "id": "3f6c1a2e-9b4d-4e8f-a1c2-7d9e0f1a2b3c",
      "workspace_id": "8a1f2c3d-4b5e-4f60-9a7b-1c2d3e4f5a6b",
      "custom_domain_id": null,
      "domain": "clik.is",
      "domain_status": "default",
      "title": "Summer sale",
      "description": "",
      "short_code": "summer-sale",
      "destination_url": "https://example.com/summer-sale",
      "status": "active",
      "expires_at": null,
      "expired_redirect_url": null,
      "folder_id": "6b7c8d9e-0f1a-4b2c-8d3e-4f5a6b7c8d9e",
      "ab_testing": [],
      "geo_targeting": null,
      "device_targeting": null,
      "qr_metadata": null,
      "og_preview": null,
      "meta_pixel_id": null,
      "tiktok_pixel_id": null,
      "ga4_measurement_id": null,
      "gtm_container_id": null,
      "has_password": false,
      "click_count": 128,
      "created_by": "c4d5e6f7-a8b9-4c0d-9e1f-2a3b4c5d6e7f",
      "created_at": "2026-10-09T09:30:00.000Z",
      "updated_at": "2026-10-09T09:30:00.000Z",
      "tags": [
        {
          "id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
          "name": "launch",
          "color": "#3b82f6"
        }
      ],
      "creator": {
        "id": "c4d5e6f7-a8b9-4c0d-9e1f-2a3b4c5d6e7f",
        "display_name": "Asha Rao",
        "email": "asha@example.com",
        "photo_url": ""
      }
    }
  ],
  "meta": {
    "total": 1,
    "limit": 20,
    "offset": 0,
    "total_is_capped": false,
    "has_more": false
  }
}
```

## Parameters

| Name        | In    | Type    | Required | Description                                                                    |
| ----------- | ----- | ------- | -------- | ------------------------------------------------------------------------------ |
| `limit`     | query | integer | no       | How many links to return. Defaults to 50, at most 200.                         |
| `offset`    | query | integer | no       | How many links to skip, for paging. Defaults to 0.                             |
| `q`         | query | string  | no       | Search term, matched against the title, slug, destination URL and description. |
| `folder_id` | query | string  | no       | Only links in this folder.                                                     |
| `status`    | query | string  | no       | Only links with this status. `active` and `expired` also look at `expires_at`. |
| `tags`      | query | string  | no       | Comma-separated tag ids. Returns links that have at least one of them.         |
| `sort_by`   | query | string  | no       | Field to sort by.                                                              |
| `order`     | query | string  | no       | Sort direction.                                                                |

## Common errors

| Status | Code           | When                                                                  |
| ------ | -------------- | --------------------------------------------------------------------- |
| 401    | `UNAUTHORIZED` | The API key is missing, malformed or unknown.                         |
| 403    | `FORBIDDEN`    | The `Workspace-Id` header names a different workspace than the key's. |
| 429    | `RATE_LIMITED` | The key went over its per-minute request limit.                       |

## Good to know

* `data` is an array of links, and the paging info is in `meta`, next to `data`.
* `meta.total` stops counting at 10,000. When `meta.total_is_capped` is `true`, page with `meta.has_more` instead of comparing against `total`.
* `limit` is at most 200. A bigger number is cut to 200, not refused.
* `q` searches the title, slug, destination URL and description. It is a contains-match, not a full-text search.
* `status=active` leaves out links whose `expires_at` has passed, even if their stored status still says `active`.
* `tags` takes tag ids, comma-separated. A link matches if it has at least one of them.
* Deleted links never appear. Archived links do, unless you filter by `status`.

---

Source: https://clik.so/docs/api/links/list-links