Screenshot

Taking a screenshot with Microlink API requires two parameters: the target url and screenshot.

Use screenshot: true for the default capture, or pass an object when you need screenshot-specific options such as fullPage, element, or type.

The following examples show how to use the Microlink API with CLI, cURL, JavaScript, Python, Ruby, PHP & Golang, targeting 'https://github.com/microlinkhq' URL with 'screenshot' API parameter:

CLI Microlink API example

microlink https://github.com/microlinkhq&screenshot

cURL Microlink API example

curl -G "https://api.microlink.io" \
  -d "url=https://github.com/microlinkhq" \
  -d "screenshot=true"

JavaScript Microlink API example

import mql from '@microlink/mql'

const { data } = await mql('https://github.com/microlinkhq', {
  screenshot: true
})

Python Microlink API example

import requests

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

querystring = {
    "url": "https://github.com/microlinkhq",
    "screenshot": "true"
}

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

print(response.json())

Ruby Microlink API example

require 'uri'
require 'net/http'

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

params = {
  url: "https://github.com/microlinkhq",
  screenshot: "true"
}

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

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

$params = [
    "url" => "https://github.com/microlinkhq",
    "screenshot" => "true"
];

$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://github.com/microlinkhq")
    q.Set("screenshot", "true")
    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))
}

import mql from '@microlink/mql'

const { data } = await mql('https://github.com/microlinkhq', {
  screenshot: true
})

Hit Run to see the live result. The generated asset is returned under data.screenshot.url.

That's the basic flow: Microlink opens a headless browser, renders the page, captures the current viewport, stores the image on the CDN, and returns the resulting asset metadata.

MQL installation

To run the JavaScript examples with MQL, install @microlink/mql:

npm install @microlink/mql --save

It works in Node.js, Edge runtimes, and the browser. See the MQL installation guide for the environment-specific setup.

If you are using another language, you do not need to install MQL to follow this guide. You can use the terminal examples or call the API directly from any HTTP client.

How screenshot options work

As soon as you want to customize the capture, switch from true to a screenshot object:

{
  url: 'https://microlink.io',
  screenshot: {
    fullPage: true,
    type: 'jpeg'
  },
  meta: false
}

This guide uses the nested object form consistently because it's the clearest way to group screenshot-specific options. In raw query strings, the same options are expressed with dot notation such as screenshot.fullPage=true.

The response

The screenshot field in the response contains everything you need to reuse the generated asset:

{
  "status": "success",
  "data": {
    "screenshot": {
      "url": "https://microlink-cdn.s3.amazonaws.com/s/...",
      "type": "png",
      "size": 183864,
      "width": 1920,
      "height": 1080,
      "size_pretty": "184 kB"
    }
  }
}

Most application workflows use data.screenshot.url directly. It is a CDN-hosted asset you can store, cache, or pass to another service.

Choose a delivery mode

You have two good ways to consume screenshots:

Need	Best option	Why
You want JSON plus screenshot metadata	Default response	You get `data.screenshot.url`, dimensions, type, and size
You need an image URL for HTML, CSS, Markdown, or OG tags	`embed: 'screenshot.url'`	The API URL behaves like a direct image

If you already know you want to use the screenshot in markup, skip straight to delivery and embedding.

Skip metadata for faster responses

By default, the API also extracts page metadata (title, description, images, etc.). If you only need the screenshot, disable it:

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

CLI Microlink API example

microlink https://github.com/microlinkhq&screenshot

cURL Microlink API example

curl -G "https://api.microlink.io" \
  -d "url=https://github.com/microlinkhq" \
  -d "screenshot=true" \
  -d "meta=false"

JavaScript Microlink API example

import mql from '@microlink/mql'

const { data } = await mql('https://github.com/microlinkhq', {
  screenshot: true,
  meta: false
})

Python Microlink API example

import requests

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

querystring = {
    "url": "https://github.com/microlinkhq",
    "screenshot": "true",
    "meta": "false"
}

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

print(response.json())

Ruby Microlink API example

require 'uri'
require 'net/http'

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

params = {
  url: "https://github.com/microlinkhq",
  screenshot: "true",
  meta: "false"
}

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

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

$params = [
    "url" => "https://github.com/microlinkhq",
    "screenshot" => "true",
    "meta" => "false"
];

$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://github.com/microlinkhq")
    q.Set("screenshot", "true")
    q.Set("meta", "false")
    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))
}

import mql from '@microlink/mql'

const { data } = await mql('https://github.com/microlinkhq', {
  screenshot: true,
  meta: false
})

Setting meta: false skips metadata extraction, which is usually the biggest speedup for screenshot-only requests.

If you still need a couple metadata fields, meta also accepts an object for selective extraction. See the meta reference.

Using the raw URL

You can call the API directly from your browser address bar or from any HTTP client:

https://api.microlink.io?url=https://github.com/microlinkhq&screenshot=true&meta=false

That returns JSON. To make the API URL behave like a direct image instead, use embed=screenshot.url in the delivery and embedding guide.

Free tier and API key

The Microlink API works without an API key. You get 50 free requests per day, which is enough to test the full screenshot flow and most of the examples in this guide.

For production usage, you'll usually want a plan. It unlocks features such as configurable TTL, stale-while-revalidate caching, custom filenames, custom headers, and proxy.

To authenticate, pass your API key as the x-api-key header:

CLI Microlink API example

microlink https://github.com/microlinkhq&screenshot --api-key YOUR_API_TOKEN

cURL Microlink API example

curl -G "https://api.microlink.io" \
  -H "x-api-key: YOUR_API_TOKEN" \
  -d "url=https://github.com/microlinkhq" \
  -d "screenshot=true" \
  -d "meta=false"

JavaScript Microlink API example

import mql from '@microlink/mql'

const { data } = await mql('https://github.com/microlinkhq', {
  screenshot: true,
  meta: false,
  apiKey: "YOUR_API_TOKEN"
})

Python Microlink API example

import requests

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

querystring = {
    "url": "https://github.com/microlinkhq",
    "screenshot": "true",
    "meta": "false"
}

headers = {
    "x-api-key": "YOUR_API_TOKEN"
}

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

print(response.json())

Ruby Microlink API example

require 'uri'
require 'net/http'

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

params = {
  url: "https://github.com/microlinkhq",
  screenshot: "true",
  meta: "false"
}

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)
request['x-api-key'] = "YOUR_API_TOKEN"
response = http.request(request)

puts response.body

PHP Microlink API example

<?php

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

$params = [
    "url" => "https://github.com/microlinkhq",
    "screenshot" => "true",
    "meta" => "false"
];

$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",
    CURLOPT_HTTPHEADER => [
        "x-api-key: YOUR_API_TOKEN"
    ]
]);

$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://github.com/microlinkhq")
    q.Set("screenshot", "true")
    q.Set("meta", "false")
    u.RawQuery = q.Encode()

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

    req.Header.Set("x-api-key", "YOUR_API_TOKEN")

    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))
}

import mql from '@microlink/mql'

const { data } = await mql('https://github.com/microlinkhq', {
  screenshot: true,
  meta: false,
  apiKey: "YOUR_API_TOKEN"
})

You can enter your API key in any interactive example by clicking the key icon in the terminal toolbar.

Throughout this guide, features that require a plan are marked inline.

See the authentication and rate limit docs for details.

What's next

Pick the next step based on the result you want:

Customizing output — change what gets captured and how the final image looks.
Browser settings — control device emulation, viewport, color scheme, media type, and JavaScript.
Page interaction — prepare the page before capture by waiting, clicking, scrolling, or injecting code.
Delivery and embedding — choose between JSON + CDN URLs or direct embeddable image responses.
Caching and performance — tune freshness, cache behavior, and request speed.
Private pages — capture logged-in or header-dependent pages safely.
Troubleshooting — debug timeouts, antibot protections, wrong captures, and plan-related errors.