Welcome to microlink API!
You can use it to retrieve relevant information from any link. The service is oriented to build embed previsualizations of third-party links in your project.
From the url provided as input, we can detect the following information:
  • author — eg. SpaceX
    A human-readable representation of the author's name.
  • date — eg. 2018-01-24T18:39:47.000Z
    An ISO 8601 representation of the date the article was published.
  • description — eg. First static fire test of Falcon Heavy…
    The publisher's chosen description of the article.
  • image — eg. https://cdninstagram.com/…/26867070_171196260320789.jpg
    An image URL that best represents the article.
  • video — eg. https://cdninstagram.com/…/26867070_171196260320789.mp4
    A video URL that best represents the article.
  • lang — eg. en
    An ISO 639-1 representation of the url content language.
  • logo — eg. https://www.instagram.com/static/images/ico/favicon-192.png/b407fa101800.png
    An image URL that best represents the publisher brand.
  • publisher — eg. Instagram
    A human-readable representation of the publisher's name.
  • title — eg. SpaceX on Instagram
    The publisher's chosen title of the article.
  • url — eg. https://www.instagram.com/p/BeV6tOhFUor
    The URL of the article.
Complementing the information obtained, we provide you a set of extra features that enrich your links previsualizations and improve your engagement:
  • Take a screenshot of the website (partial or full page).
  • Get a predominant color palette per each image detected.
  • Make easy embed content directly in your HTML markup.
  • Prerendering mode, useful for getting more information from websites that use client-side frameworks.
  • Export to PDF (soon, ping us if you are interested!)
Entering a URL, you will receive the information behind the link.
curl https://api.microlink.io?url=https://www.instagram.com/p/BeV6tOhFUor
The above API request generate the following response:
  "status": "success",
  "data": {
    "lang": "en",
    "author": "spacex",
    "title": "SpaceX on Instagram: “First static fire test of Falcon Heavy complete—one step closer to first test flight!”",
    "publisher": "Instagram",
    "image": {
      "width": 1080,
      "height": 607,
      "type": "jpg",
      "url": "https://scontent-iad3-1.cdninstagram.com/vp/68093557a1e21266afd48b71782770fc/5A837225/t51.2885-15/s1080x1080/e15/fr/26867070_171196260320789_7698587573655961600_n.jpg"
    "description": "“First static fire test of Falcon Heavy complete—one step closer to first test flight!”",
    "date": "2018-01-24T18:39:47.000Z",
    "video": {
      "width": 640,
      "height": 360,
      "type": "h264",
      "url": "https://scontent-iad3-1.cdninstagram.com/vp/8b8a3ca167df137bb67cc4c3025b754b/5A836752/t50.2886-16/26680591_1497085977080751_971884209264132096_n.mp4"
    "logo": {
      "width": 192,
      "height": 192,
      "type": "png",
      "url": "https://www.instagram.com/static/images/ico/favicon-192.png/b407fa101800.png"
    "url": "https://www.instagram.com/p/BeV6tOhFUor"
The API is shipped as a microservice exposed as an HTTP service over SSL.
For the Free plan, the endpoint is https://api.microlink.io
Under a Professional plans, the endpoint is https://pro.microlink.io.
Just call / with method GET. Nothing else.
We apply different API quota based pricing plans.
Unauthenticated requests use Free plans. It doesn't need to do nothing additional.
Under a Professional plans, you need to authenticated your requests.
It should be done providing the header x-api-key with your API Key as value in all your requests.
If you have any trouble, please contact us.
The authentication will be done adding your API Key as value of the x-api-key header on your requests:
curl --header "x-api-key: MyApiToken" https://pro.microlink.io?url=http://a.co/cWDWLda -i | grep "X-Pricing-Plan"
You can check the pricing plan associated with the request with x-pricing-plan header on the response:
x-pricing-plan: pro
For the Free plan, we allow a maximum of 500 requests every 24 hours and one request per second.
We limit the number of calls you can make over a certain period of time. Rate limits vary and are specified by the following header in all responses:
X-Rate-Limit-LimitThe maximum number of requests that the consumer is permitted to make per minute.
X-Rate-Limit-RemainingThe number of requests remaining in the current rate limit window.
X-Rate-Limit-ResetThe time at which the current rate limit window resets in UTC epoch seconds.
Under the Professional plan, rate limits start from 1,000 requests every 24 hours with unlimited concurrency.
When the rate limit is exceeded an error is returned with the status 429 Too Many Requests.
When you exceeded your daily quota, you need to wait until quota reset or increment your plan. See pricing for more information.
If you already have a Professional plan but you need to increment your daily quota, contact us.
You can check your rate limit quota with x-rate header on the response:
curl --header "x-api-key: MyApiToken" https://pro.microlink.io?url=http://a.co/cWDWLda -i | grep -i "x-pricing-plan"
It should be looks like:
x-rate-limit-reset: 86400
x-rate-limit-remaining: 497
x-rate-limit-limit: 500
All the responses as served as JSON – unless you use the embedded support.
Our response format is based on JSend specification.
This means that every API call generates a response with status, data and message fields.


type: string
The status associated with the response. The value can be:
successThe request was resolved successfully. Associated with 2xx HTTP status code.
failThe request failed. Probably a missing or wrong value for a parameter. Associated with 4xx HTTP status code.
errorUh oh. Something unexpected happened. Associated with 5xx HTTP status code.
A simple rule here is, if the request was resolved successfully, then the success status will be associated. In other case check for fail or error.


type: object
Your API response payload. Here you can find all the information related with the link provided, like description, title, image, etc.


type: string
An additional field to attach extra information, such as an error message or explanation.
In order to improve response timing, we follow a query caching policy for successive API calls.
  • The first time you query for a resource that not was previously served, we will create it.
  • The successive requests for the resource will consume the cached version of the resource.
The order of the query parameters doesn't matter.
For the Free plan, the first request will be cached for the next 5 days.
If you have the Professional plan, your caching policy can be custom, adapting the expiration to your user case. Please, contact us.
If you want to invalidate a response cache and regenerate the cache value you should use the force parameter.
The first time an uncached resource is queried, the API will extract the information from the link:
curl https://api.microlink.io/?url=https%3A%2F%2Fwww.reddit.com | grep -i "x-cache"
You can check that from x-cache headers of the response. First time, the value will be MISS:
x-cache: MISS
Now if you query again for the same resource, a cached version will be served based on the first request, and X-Cache value will be HIT:
x-cache: HIT
type: string
The URL for getting information based on the content.
At least you need to provide an url to get information
curl https://api.microlink.io/?url=https://theverge.com
type: boolean|string
default 'auto'
You define how the content will be searched from the target URL.
Prerendering is a technique for retrieving the HTML content simulating the user browser navigation.
Although it will provide better data, it will take more time to respond. Most popular services do not need it.
In order to improve the response timing, we provide an auto value by default. This means that the service will determinate if the target URL need or not use prerendering technique.
If you want to enable/disable prerendering, do it explicitly
curl https://api.microlink.io/?url=https://reddit.com&prerender=false
type: boolean|string
default false
Take a screenshot of the website. The image will be hosted at imgur.com.

Device emulation

The API supports take screenshots using different viewport configuration.
In order to setup the viewport settings, we provide device that it's a list of device presets viewports you can use.
To use it just provide one of the supported device names:
device descriptorwidthheightscalemobile?touch?landscape?
blackberry z303606402truetruefalse
blackberry z30 landscape6403602truetruetrue
blackberry playbook60010241truetruefalse
blackberry playbook landscape10246001truetruetrue
galaxy note 33606403truetruefalse
galaxy note 3 landscape6403603truetruetrue
galaxy note ii3606402truetruefalse
galaxy note ii landscape6403602truetruetrue
galaxy s iii3606402truetruefalse
galaxy s iii landscape6403602truetruetrue
galaxy s53606403truetruefalse
galaxy s5 landscape6403603truetruetrue
kindle fire hdx80012802truetruefalse
kindle fire hdx landscape12808002truetruetrue
lg optimus l703846401.25truetruefalse
lg optimus l70 landscape6403841.25truetruetrue
macbook pro 1312808001falsefalsefalse
macbook pro 1514409001falsefalsefalse
microsoft lumia 5506403602truetruefalse
microsoft lumia 9503606404truetruefalse
microsoft lumia 950 landscape6403604truetruetrue
nexus 1080012802truetruefalse
nexus 10 landscape12808002truetruetrue
nexus 43846402truetruefalse
nexus 4 landscape6403842truetruetrue
nexus 53606403truetruefalse
nexus 5 landscape6403603truetruetrue
nexus 5x4127322.625truetruefalse
nexus 5x landscape7324122.625truetruetrue
nexus 64127323.5truetruefalse
nexus 6 landscape7324123.5truetruetrue
nexus 6p4127323.5truetruefalse
nexus 6p landscape7324123.5truetruetrue
nexus 76009602truetruefalse
nexus 7 landscape9606002truetruetrue
nokia lumia 5203205331.5truetruefalse
nokia lumia 520 landscape5333201.5truetruetrue
nokia n94808541truetruefalse
nokia n9 landscape8544801truetruetrue
imac 21.5198010801falsefalsefalse
imac 27256014401falsefalsefalse
ipad mini76810242truetruefalse
ipad mini landscape10247682truetruetrue
ipad pro102413662truetruefalse
ipad pro landscape136610242truetruetrue
ipad landscape10247682truetruetrue
iphone 43204802truetruefalse
iphone 4 landscape4803202truetruetrue
iphone 53205682truetruefalse
iphone 5 landscape5683202truetruetrue
iphone 63756672truetruefalse
iphone 6 plus4147363truetruefalse
iphone 6 plus landscape7364143truetruetrue
iphone 6 landscape6673752truetruetrue

Specific parameters

Although device is a list of popular device presets, you can setup viewports settings manually:
device_scale_factornumberSpecify device scale factor (defaults to 1).
full_pagebooleanWhen true, takes a screenshot of the full scrollable page (defaults to false).
has_touchboolean or stringSpecifies if viewport supports touch events (defaults to false).
heightnumber Page height in pixels.
is_landscapeboolean Specifies if viewport is in landscape mode (defaults to false).
is_mobileboolean Whether the meta viewport tag is taken into account (defaults to false).
omit_backgroundboolean Hides default white background and allows capturing screenshots with transparency (defaults to true).
qualitynumber The quality of the image, between 0 to 100. Not applicable to 'png' images.
typestring Specify screenshot type, could be either 'jpeg' or 'png' (defaults to 'png').
widthnumber Page width in pixels.
user_agentstring Specify the user agent to use.
When you take a screenshot snapshot such as
curl https://api.microlink.io/?url=https%3A%2F%2Fproducthunt.com&screenshot&filter=screenshot
The image will be hosted at imgur.com as png by default.
  "status": "success",
  "data": {
    "screenshot": {
      "url": "https://i.imgur.com/Jv9yqlI.png",
      "type": "png",
      "width": 1280,
      "height": 800
Providing a device name supported as value for screenshot, we will take the screenshot using the specific device settings (viewport, width, height, etc).
  style="max-width: 250px"
type: boolean
default false
Enabling it will return you more information related with color schema of the images detected:
palettearrayA collection of hexadecimal colors from most dominant color to least.
background_colorstringThe best color with good WCAG contrast ratio that can be used as background color representation of the image.
colorstringThe best color overlayed over background_color.
alternative_colorstringIt will be the second best color. If there are only two colors parsed, it will default to color.
Adding palette as query string parameter in your API call makes it possible to get more information about your images color composition:
curl https://api.microlink.io/?url=https://news.ycombinator.com&palette&filter=image
  "status": "success",
  "data": {
    "image": {
      "width": 18,
      "height": 18,
      "type": "gif",
      "url": "https://news.ycombinator.com/y18.gif",
      "palette": [
      "background_color": "#FCA46C",
      "color": "#712D01",
      "alternative_color": "#813201"
type: string
A comma-separated list of the requested values.
This parameter has been designed to make API payload tiny as possible, improving response bandwidth timing.
It's a good practice to filter just the values that you're going to consume:
curl curl https://api.microlink.io/?url=https://news.ycombinator.com&filter=url,title
  "status": "success",
  "data": {
    "url": "https://news.ycombinator.com/",
    "title": "Hacker News"


type: string
The embed parameter is for embedding a field directly in your HTML markup, using the properly encoding (text, images, etc).
You can use dot notation to reference a nested data field of the payload.
For example, if you want to embed an image just provide embed=image.src and the image will be rendered.
You can call the API directly from a html tag:
It will render the hacker news logo:
type: boolean
default false
By default the API will be cache consecutive API calls. See cache section for more information.
This parameter has been designed to invalidate the cache responses, avoiding the minimum time necessary to revalidate them.
Providing it, you are forcing to invalidate the current state of the cache for the response and generate a new one.