# Social previews and pixels

Set the title, text and image that show when a Clikso short link is shared, and add Meta, TikTok, GA4 or GTM tracking, via the API.

> **In short:**
>
> When someone shares a short link, apps like WhatsApp and LinkedIn show a preview card. `og_preview` lets you choose its title, text and image. Pixel fields add Meta, TikTok, GA4 or Google Tag Manager tracking to each visit. Both need the Starter plan or higher.

## You need

* **API key:** **Write** to change a link. **Read** is enough to fetch a page’s current preview.
* **Role:** Editor or admin to change a link. Any member can fetch a preview.
* **Plan:** **Starter** or higher to set a custom preview or a pixel. Fetching a preview works on every plan.

## See a page’s current preview

Before you write your own, see what the page already shows. Send its URL:

```bash
curl -X POST "https://app.clik.so/api/links/og-preview" \
  -H "Authorization: Bearer $CLIKSO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/summer-sale"
  }'
```

Response 200:

```json
{
  "status": 200,
  "success": true,
  "message": "Success",
  "data": {
    "og_title": "Summer sale — 30% off everything",
    "og_description": "Our biggest sale of the year ends Sunday.",
    "og_image_url": "https://example.com/images/summer-sale.jpg"
  }
}
```

You always get a `200`. If Clikso cannot read the page, the title and text come back empty, and the image is the site’s icon. So the card is never blank.

## Set your own preview

Send `og_preview` with any of its three fields. "OG" stands for Open Graph, the tags that apps read to build a card.

```bash
curl -X PUT "https://app.clik.so/api/links/3f6c1a2e-9b4d-4e8f-a1c2-7d9e0f1a2b3c" \
  -H "Authorization: Bearer $CLIKSO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "og_preview": {
      "og_title": "Summer sale — 30% off everything",
      "og_description": "Our biggest sale of the year ends Sunday.",
      "og_image_url": "https://example.com/images/summer-sale.jpg"
    }
  }'
```

`og_image_url` must be a public `https://` image URL. The API cannot upload images, so host the image yourself first.

You can change the preview without touching the destination site. That is the main reason to use it.

## Add tracking pixels

A tracking pixel tells your ad or analytics tool that someone clicked. Send the ids you use:

```bash
curl -X PUT "https://app.clik.so/api/links/3f6c1a2e-9b4d-4e8f-a1c2-7d9e0f1a2b3c" \
  -H "Authorization: Bearer $CLIKSO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "meta_pixel_id": "123456789012345",
    "ga4_measurement_id": "G-ABC123DEF4"
  }'
```

Each id must match its tool’s format:

* `meta_pixel_id` — 6 to 20 digits.
* `tiktok_pixel_id` — 8 to 40 letters or digits.
* `ga4_measurement_id` — `G-` and then 4 to 16 capital letters or digits.
* `gtm_container_id` — `GTM-` and then 4 to 12 capital letters or digits.

## What visitors see

A plain link answers with a quick redirect (`302`). A link with a custom preview or a pixel works differently.

It answers with a small web page (`200`) that holds the preview tags and the pixels. That page then sends the visitor on with JavaScript. With pixels, it waits a moment so they can fire. This is the trade-off for previews and pixels.

## Remove a preview or a pixel

* To remove the custom preview, send `og_preview: null`. Sending `og_preview: {}` works too.
* To remove a pixel, send its field as `null`, like `meta_pixel_id: null`.

```bash
curl -X PUT "https://app.clik.so/api/links/3f6c1a2e-9b4d-4e8f-a1c2-7d9e0f1a2b3c" \
  -H "Authorization: Bearer $CLIKSO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "og_preview": null,
    "meta_pixel_id": null
  }'
```

Removing works on every plan.

## What you get back

* **Fetch a preview:** `200` with `og_title`, `og_description` and `og_image_url` in `data`.
* **Update a link:** `200` with the whole link. `og_preview` holds what you set, or `null` if it was never set. The four pixel fields hold their ids or `null`.

## Common errors

| Status | Code               | What it means                                                                                                              | What to do                                                                                               |
| ------ | ------------------ | -------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| 402    | `UPGRADE_REQUIRED` | The workspace is below Starter. `details.field` names the field, and `details.required_plan` is `starter`.                 | Leave the field out, or upgrade the workspace.                                                           |
| 403    | `FORBIDDEN`        | The key has only Read permission, or its owner is a viewer.                                                                | Check the key’s permission and your role. If you send `Workspace-Id`, it must match the key’s workspace. |
| 422    | `VALIDATION_ERROR` | A pixel id has the wrong format (`error.details` names each bad field), or the preview URL is not a public `http(s)` page. | Fix the field and send the request again.                                                                |
| 429    | `RATE_LIMITED`     | The workspace fetched too many previews this minute. Wait for `Retry-After`.                                               | Wait the number of seconds in the `Retry-After` header, then try again.                                  |

## Good to know

* Fetching previews is limited to 30 calls a minute per workspace, shared by every key.
* The preview fetch only reads public pages. Private addresses, like `localhost` or a home network, are refused.
* Apps that already showed a card may keep their old copy for a while.
* With a pixel, the visitor sees a short pause before the page opens.
* Setting the same preview or pixel a link already has always works, even after a downgrade.
* See every field on [Update a link](https://clik.so/docs/api/links/update-link).

---

Source: https://clik.so/docs/guides/social-previews