## Table of Contents

- [The embed URL is public](#the-embed-url-is-public)
- [Embed an authenticated dashboard PRO](#embed-an-authenticated-dashboard-pro)
  - [CLI Microlink API example](#cli-microlink-api-example)
  - [cURL Microlink API example](#curl-microlink-api-example)
  - [JavaScript Microlink API example](#javascript-microlink-api-example)
  - [Python Microlink API example](#python-microlink-api-example)
  - [Ruby Microlink API example](#ruby-microlink-api-example)
  - [PHP Microlink API example](#php-microlink-api-example)
  - [Golang Microlink API example](#golang-microlink-api-example)
- [Front public embeds with a proxy server](#front-public-embeds-with-a-proxy-server)
- [Embed sites blocked by antibot systems PRO](#embed-sites-blocked-by-antibot-systems-pro)
  - [CLI Microlink API example](#cli-microlink-api-example-1)
  - [cURL Microlink API example](#curl-microlink-api-example-1)
  - [JavaScript Microlink API example](#javascript-microlink-api-example-1)
  - [Python Microlink API example](#python-microlink-api-example-1)
  - [Ruby Microlink API example](#ruby-microlink-api-example-1)
  - [PHP Microlink API example](#php-microlink-api-example-1)
  - [Golang Microlink API example](#golang-microlink-api-example-1)
- [Geofenced content](#geofenced-content)
- [When private embeds still fail](#when-private-embeds-still-fail)
- [Next step](#next-step)

---

[API](https://microlink.io/docs/api/getting-started/overview)

[GUIDES](https://microlink.io/docs/guides) [MQL](https://microlink.io/docs/mql/getting-started/overview) [SDK](https://microlink.io/docs/sdk/getting-started/overview) [CARDS](https://microlink.io/docs/cards/getting-started/overview)

API GUIDES MQL SDK CARDS

Getting Started

[Overview](https://microlink.io/docs/guides)

[What is Microlink](https://microlink.io/docs/guides/what-is-microlink)

[Screenshot](https://microlink.io/docs/guides/screenshot)

[Customizing output](https://microlink.io/docs/guides/screenshot/customizing-output)

[Browser settings](https://microlink.io/docs/guides/screenshot/browser-settings)

[Page interaction](https://microlink.io/docs/guides/screenshot/page-interaction)

[Delivery and embedding](https://microlink.io/docs/guides/screenshot/embedding)

[Caching and performance](https://microlink.io/docs/guides/screenshot/caching-and-performance)

[Private pages](https://microlink.io/docs/guides/screenshot/private-pages)

[Troubleshooting](https://microlink.io/docs/guides/screenshot/troubleshooting)

[Data extraction](https://microlink.io/docs/guides/data-extraction)

[Defining rules](https://microlink.io/docs/guides/data-extraction/defining-rules)

[Page preparation](https://microlink.io/docs/guides/data-extraction/page-preparation)

[Delivery and response shaping](https://microlink.io/docs/guides/data-extraction/delivery-and-response)

[Caching and performance](https://microlink.io/docs/guides/data-extraction/caching-and-performance)

[Private pages](https://microlink.io/docs/guides/data-extraction/private-pages)

[Troubleshooting](https://microlink.io/docs/guides/data-extraction/troubleshooting)

[Embed](https://microlink.io/docs/guides/embed)

[SDK](https://microlink.io/docs/guides/embed/sdk)

[Iframe parameter](https://microlink.io/docs/guides/embed/iframe)

[Custom HTML/CSS](https://microlink.io/docs/guides/embed/metadata-api)

[Custom previews with AI](https://microlink.io/docs/guides/embed/custom-previews-with-ai)

[Caching and performance](https://microlink.io/docs/guides/embed/caching-and-performance)

[Private pages and proxy](https://microlink.io/docs/guides/embed/private-pages-and-proxy)

[Troubleshooting](https://microlink.io/docs/guides/embed/troubleshooting)

[Markdown](https://microlink.io/docs/guides/markdown)

[Choosing scope](https://microlink.io/docs/guides/markdown/choosing-scope)

[Delivery and response shaping](https://microlink.io/docs/guides/markdown/delivery-and-response)

[Function](https://microlink.io/docs/guides/function)

[PDF](https://microlink.io/docs/guides/pdf)

[Page size and layout](https://microlink.io/docs/guides/pdf/page-size-and-layout)

[Page preparation](https://microlink.io/docs/guides/pdf/page-preparation)

[Delivery and embedding](https://microlink.io/docs/guides/pdf/embedding)

[Caching and performance](https://microlink.io/docs/guides/pdf/caching-and-performance)

[Private pages](https://microlink.io/docs/guides/pdf/private-pages)

[Troubleshooting](https://microlink.io/docs/guides/pdf/troubleshooting)

[Metadata](https://microlink.io/docs/guides/metadata)

[Choosing fields](https://microlink.io/docs/guides/metadata/choosing-fields)

[Extending results](https://microlink.io/docs/guides/metadata/extending-results)

[Delivery and response shaping](https://microlink.io/docs/guides/metadata/delivery-and-response)

[Page preparation](https://microlink.io/docs/guides/metadata/page-preparation)

[Caching and performance](https://microlink.io/docs/guides/metadata/caching-and-performance)

[Private pages](https://microlink.io/docs/guides/metadata/private-pages)

[Troubleshooting](https://microlink.io/docs/guides/metadata/troubleshooting)

[Insights](https://microlink.io/docs/guides/insights)

[Technology detection](https://microlink.io/docs/guides/insights/technology-detection)

[Lighthouse reports](https://microlink.io/docs/guides/insights/lighthouse-reports)

[Caching and performance](https://microlink.io/docs/guides/insights/caching-and-performance)

[Troubleshooting](https://microlink.io/docs/guides/insights/troubleshooting)

[Common patterns](https://microlink.io/docs/guides/common/caching)

[Caching patterns](https://microlink.io/docs/guides/common/caching)

[Private pages](https://microlink.io/docs/guides/common/private-pages)

[Proxy](https://microlink.io/docs/guides/common/proxy)

[Troubleshooting](https://microlink.io/docs/guides/common/troubleshooting)

[Production patterns](https://microlink.io/docs/guides/common/production-patterns)

API GUIDES MQL SDK CARDS

Getting Started

[Overview](https://microlink.io/docs/guides)

[What is Microlink](https://microlink.io/docs/guides/what-is-microlink)

[Screenshot](https://microlink.io/docs/guides/screenshot)

[Customizing output](https://microlink.io/docs/guides/screenshot/customizing-output)

[Browser settings](https://microlink.io/docs/guides/screenshot/browser-settings)

[Page interaction](https://microlink.io/docs/guides/screenshot/page-interaction)

[Delivery and embedding](https://microlink.io/docs/guides/screenshot/embedding)

[Caching and performance](https://microlink.io/docs/guides/screenshot/caching-and-performance)

[Private pages](https://microlink.io/docs/guides/screenshot/private-pages)

[Troubleshooting](https://microlink.io/docs/guides/screenshot/troubleshooting)

[Data extraction](https://microlink.io/docs/guides/data-extraction)

[Defining rules](https://microlink.io/docs/guides/data-extraction/defining-rules)

[Page preparation](https://microlink.io/docs/guides/data-extraction/page-preparation)

[Delivery and response shaping](https://microlink.io/docs/guides/data-extraction/delivery-and-response)

[Caching and performance](https://microlink.io/docs/guides/data-extraction/caching-and-performance)

[Private pages](https://microlink.io/docs/guides/data-extraction/private-pages)

[Troubleshooting](https://microlink.io/docs/guides/data-extraction/troubleshooting)

[Embed](https://microlink.io/docs/guides/embed)

[SDK](https://microlink.io/docs/guides/embed/sdk)

[Iframe parameter](https://microlink.io/docs/guides/embed/iframe)

[Custom HTML/CSS](https://microlink.io/docs/guides/embed/metadata-api)

[Custom previews with AI](https://microlink.io/docs/guides/embed/custom-previews-with-ai)

[Caching and performance](https://microlink.io/docs/guides/embed/caching-and-performance)

[Private pages and proxy](https://microlink.io/docs/guides/embed/private-pages-and-proxy)

[Troubleshooting](https://microlink.io/docs/guides/embed/troubleshooting)

[Markdown](https://microlink.io/docs/guides/markdown)

[Choosing scope](https://microlink.io/docs/guides/markdown/choosing-scope)

[Delivery and response shaping](https://microlink.io/docs/guides/markdown/delivery-and-response)

[Function](https://microlink.io/docs/guides/function)

[PDF](https://microlink.io/docs/guides/pdf)

[Page size and layout](https://microlink.io/docs/guides/pdf/page-size-and-layout)

[Page preparation](https://microlink.io/docs/guides/pdf/page-preparation)

[Delivery and embedding](https://microlink.io/docs/guides/pdf/embedding)

[Caching and performance](https://microlink.io/docs/guides/pdf/caching-and-performance)

[Private pages](https://microlink.io/docs/guides/pdf/private-pages)

[Troubleshooting](https://microlink.io/docs/guides/pdf/troubleshooting)

[Metadata](https://microlink.io/docs/guides/metadata)

[Choosing fields](https://microlink.io/docs/guides/metadata/choosing-fields)

[Extending results](https://microlink.io/docs/guides/metadata/extending-results)

[Delivery and response shaping](https://microlink.io/docs/guides/metadata/delivery-and-response)

[Page preparation](https://microlink.io/docs/guides/metadata/page-preparation)

[Caching and performance](https://microlink.io/docs/guides/metadata/caching-and-performance)

[Private pages](https://microlink.io/docs/guides/metadata/private-pages)

[Troubleshooting](https://microlink.io/docs/guides/metadata/troubleshooting)

[Insights](https://microlink.io/docs/guides/insights)

[Technology detection](https://microlink.io/docs/guides/insights/technology-detection)

[Lighthouse reports](https://microlink.io/docs/guides/insights/lighthouse-reports)

[Caching and performance](https://microlink.io/docs/guides/insights/caching-and-performance)

[Troubleshooting](https://microlink.io/docs/guides/insights/troubleshooting)

[Common patterns](https://microlink.io/docs/guides/common/caching)

[Caching patterns](https://microlink.io/docs/guides/common/caching)

[Private pages](https://microlink.io/docs/guides/common/private-pages)

[Proxy](https://microlink.io/docs/guides/common/proxy)

[Troubleshooting](https://microlink.io/docs/guides/common/troubleshooting)

[Production patterns](https://microlink.io/docs/guides/common/production-patterns)

[Copy for LLM](https://microlink.io/docs/guides/embed/private-pages-and-proxy.md "Copy content for LLM")

\|

[View as Markdown](https://microlink.io/docs/guides/embed/private-pages-and-proxy.md "View content as Markdown")

Most embeds are for public pages. The hard cases are private dashboards, region-locked products, and sites that block headless browsers. Both require

PRO

features — `headers`, `x-api-header-*`, and `proxy` — plus extra discipline because embed URLs are public by nature.

The shared patterns live in [private pages patterns](https://microlink.io/docs/guides/common/private-pages) and [proxy patterns](https://microlink.io/docs/guides/common/proxy). This page covers the embed-specific setup.

## The embed URL is public

Whatever you put in an embed URL ends up in HTML, browser devtools, server logs, social previews, and downstream caches. That changes the threat model:

| Approach                                               | Safe in public embed URLs?                          |
| ------------------------------------------------------ | --------------------------------------------------- |
| `headers={ 'accept-language': 'es-ES' }` (locale-only) | Yes — value is non-sensitive                        |
| `headers={ 'cookie': '...' }` (sensitive)              | **No** — exposes credentials                        |
| `x-api-header-cookie: ...` request header              | Yes — sent server-to-server, never in the embed URL |
| `proxy=https://user:pass@...` query param              | **No** — leaks proxy credentials                    |
| `proxy` set inside an MQL call from the server         | Yes — never reaches the browser                     |

The rule: only **non-sensitive** values belong in the embed URL. Everything else stays server-side, behind a backend that proxies the call to Microlink.

## Embed an authenticated dashboard PRO

Use `x-api-header-*` to forward the cookie or bearer token without exposing it:

```bash
curl -G https://pro.microlink.io \

  -d url=https://app.example.com/dashboard \

  -d screenshot=true \

  -d embed=screenshot.url \

  -d meta=false \

  -H 'x-api-key: YOUR_API_TOKEN' \

  -H 'x-api-header-cookie: session=abc123'
```

The response is the screenshot bytes — usable as an `<img src>` in an internal portal or a logged-in user's email. The cookie never reaches the browser because the request lives on your backend.

For non-sensitive values like locale or accept-language, the URL-based `headers` parameter is fine:

The following examples show how to use the Microlink API with CLI, cURL, JavaScript, Python, Ruby, PHP & Golang, targeting 'https://example.com/pricing' URL with 'screenshot', 'meta', 'headers' & 'embed' API parameters:

### CLI Microlink API example

```bash
microlink https://example.com/pricing&screenshot&headers.Accept-Language=es-ES&embed=screenshot.url
```

### cURL Microlink API example

```bash
curl -G "https://api.microlink.io" \
  -d "url=https://example.com/pricing" \
  -d "screenshot=true" \
  -d "meta=false" \
  -d "headers.Accept-Language=es-ES" \
  -d "embed=screenshot.url"
```

### JavaScript Microlink API example

```javascript
import mql from '@microlink/mql'

const { data } = await mql('https://example.com/pricing', {
  screenshot: true,
  meta: false,
  headers: {
    "Accept-Language": "es-ES"
  },
  embed: "screenshot.url"
})
```

### Python Microlink API example

```python
import requests

url = "https://api.microlink.io/"

querystring = {
    "url": "https://example.com/pricing",
    "screenshot": "true",
    "meta": "false",
    "headers.Accept-Language": "es-ES",
    "embed": "screenshot.url"
}

response = requests.get(url, params=querystring)

print(response.json())
```

### Ruby Microlink API example

```ruby
require 'uri'
require 'net/http'

base_url = "https://api.microlink.io/"

params = {
  url: "https://example.com/pricing",
  screenshot: "true",
  meta: "false",
  headers.Accept-Language: "es-ES",
  embed: "screenshot.url"
}

uri = URI(base_url)
uri.query = URI.encode_www_form(params)

http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Get.new(uri)
response = http.request(request)

puts response.body
```

### PHP Microlink API example

```php
<?php

$baseUrl = "https://api.microlink.io/";

$params = [
    "url" => "https://example.com/pricing",
    "screenshot" => "true",
    "meta" => "false",
    "headers.Accept-Language" => "es-ES",
    "embed" => "screenshot.url"
];

$query = http_build_query($params);
$url = $baseUrl . '?' . $query;

$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => $url,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "GET"
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
    echo "cURL Error #: " . $err;
} else {
    echo $response;
}
```

### Golang Microlink API example

```
package main

import (
    "fmt"
    "net/http"
    "net/url"
    "io"
)

func main() {
    baseURL := "https://api.microlink.io"

    u, err := url.Parse(baseURL)
    if err != nil {
        panic(err)
    }
    q := u.Query()
    q.Set("url", "https://example.com/pricing")
    q.Set("screenshot", "true")
    q.Set("meta", "false")
    q.Set("headers.Accept-Language", "es-ES")
    q.Set("embed", "screenshot.url")
    u.RawQuery = q.Encode()

    req, err := http.NewRequest("GET", u.String(), nil)
    if err != nil {
        panic(err)
    }

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    body, err := io.ReadAll(resp.Body)
    if err != nil {
        panic(err)
    }

    fmt.Println(string(body))
}
```

```javascript
import mql from '@microlink/mql'

const { data } = await mql('https://example.com/pricing', {

  screenshot: true,

  meta: false,

  headers: {

    "Accept-Language": "es-ES"

  },

  embed: "screenshot.url"

})
```

The locale-aware capture is rendered for an embedding without leaking secrets.

## Front public embeds with a proxy server

When the embed URL must be visible (a public OG image, a marketing card) but the request needs a key or cookies, run your own proxy:

- [@microlink/proxy](https://github.com/microlinkhq/proxy) for self-hosted Node.js / Express.
- [@microlink/edge-proxy](https://github.com/microlinkhq/edge-proxy) for Cloudflare Workers and edge runtimes.

Your public URL becomes `https://my-app.example.com/og?slug=hello`. The proxy converts that to a Microlink call with the API key and any `x-api-header-*` it needs, then streams the response back. The browser never sees the credentials.

For the architecture in detail, see [private pages patterns](https://microlink.io/docs/guides/common/private-pages).

## Embed sites blocked by antibot systems PRO

If the target page returns a CAPTCHA, an antibot challenge, or `EPROXYNEEDED`, you need a proxy.

Pro plans include **automatic proxy resolution** — the API detects the antibot provider and routes through the right pool without you setting `proxy` at all:

The following examples show how to use the Microlink API with CLI, cURL, JavaScript, Python, Ruby, PHP & Golang, targeting 'https://difficult-target.example' URL with 'screenshot', 'meta' & 'embed' API parameters:

### CLI Microlink API example

```bash
microlink https://difficult-target.example&screenshot&embed=screenshot.url
```

### cURL Microlink API example

```bash
curl -G "https://api.microlink.io" \
  -d "url=https://difficult-target.example" \
  -d "screenshot=true" \
  -d "meta=false" \
  -d "embed=screenshot.url"
```

### JavaScript Microlink API example

```javascript
import mql from '@microlink/mql'

const { data } = await mql('https://difficult-target.example', {
  screenshot: true,
  meta: false,
  embed: "screenshot.url"
})
```

### Python Microlink API example

```python
import requests

url = "https://api.microlink.io/"

querystring = {
    "url": "https://difficult-target.example",
    "screenshot": "true",
    "meta": "false",
    "embed": "screenshot.url"
}

response = requests.get(url, params=querystring)

print(response.json())
```

### Ruby Microlink API example

```ruby
require 'uri'
require 'net/http'

base_url = "https://api.microlink.io/"

params = {
  url: "https://difficult-target.example",
  screenshot: "true",
  meta: "false",
  embed: "screenshot.url"
}

uri = URI(base_url)
uri.query = URI.encode_www_form(params)

http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Get.new(uri)
response = http.request(request)

puts response.body
```

### PHP Microlink API example

```php
<?php

$baseUrl = "https://api.microlink.io/";

$params = [
    "url" => "https://difficult-target.example",
    "screenshot" => "true",
    "meta" => "false",
    "embed" => "screenshot.url"
];

$query = http_build_query($params);
$url = $baseUrl . '?' . $query;

$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => $url,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "GET"
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
    echo "cURL Error #: " . $err;
} else {
    echo $response;
}
```

### Golang Microlink API example

```
package main

import (
    "fmt"
    "net/http"
    "net/url"
    "io"
)

func main() {
    baseURL := "https://api.microlink.io"

    u, err := url.Parse(baseURL)
    if err != nil {
        panic(err)
    }
    q := u.Query()
    q.Set("url", "https://difficult-target.example")
    q.Set("screenshot", "true")
    q.Set("meta", "false")
    q.Set("embed", "screenshot.url")
    u.RawQuery = q.Encode()

    req, err := http.NewRequest("GET", u.String(), nil)
    if err != nil {
        panic(err)
    }

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    body, err := io.ReadAll(resp.Body)
    if err != nil {
        panic(err)
    }

    fmt.Println(string(body))
}
```

```javascript
import mql from '@microlink/mql'

const { data } = await mql('https://difficult-target.example', {

  screenshot: true,

  meta: false,

  embed: "screenshot.url"

})
```

On a Pro plan, the API quietly resolves the antibot when it detects one. The `x-fetch-mode` response header will be prefixed with `proxy-`.

You can also pass your own proxy URL when you have a residential or country-specific service:

```js
import mql from '@microlink/mql'

const { data } = await mql('https://example.com/pricing', {

  proxy: process.env.PROXY_URL

})

return data.screenshot.url // hand this to your embed renderer
```

Keep that call server-side — never expose the `proxy=` param in a public embed URL.

For the full proxy reference (when, how, and how to verify), see [proxy patterns](https://microlink.io/docs/guides/common/proxy).

## Geofenced content

A common embed use case: a product whose homepage shows different prices per country, and you want each region's preview cached separately. Combine `proxy` (for the IP region) with a content-hash cache buster (so each region cache is independent):

```js
async function regionalEmbed(region) {

  const proxy = PROXIES[region] // e.g. 'https://user:pass@us-proxy.example.com:8080'

  const { data } = await mql('https://example.com/pricing', {

    proxy,

    screenshot: true,

    meta: false

  })

  return data.screenshot.url

}
```

Render the resulting URL into your `<meta property="og:image">` for that locale. Pair with `ttl: '1d'` and `staleTtl: 0` so each region's variant stays warm. See [geolocation patterns](https://microlink.io/docs/guides/common/proxy#geolocation-target-region-specific-content).

## When private embeds still fail

If `x-api-header-*` and `proxy` are both set and the embed still returns wrong content:

- Confirm the cookie / token has not expired. Authenticated previews are only as fresh as the credential.
- Check `x-fetch-mode` — anything other than `proxy-*` means the proxy did not engage.
- Look for `EPROXYNEEDED` or `EAUTH` in the response body. See [error codes](https://microlink.io/docs/api/basics/error-codes).

For the rest, continue to [troubleshooting](https://microlink.io/docs/guides/embed/troubleshooting).

## Next step

For debugging missing iframes, broken images, and provider-specific quirks, see [troubleshooting](https://microlink.io/docs/guides/embed/troubleshooting).

Last updated on May 17, 2026

[Edit on GitHub](https://github.com/microlinkhq/www/blob/master/src/content/docs/guides/embed/private-pages-and-proxy.md)