API Documentation Browshot API Protocol


Not a developer?

We can write custom code for you. Send us an e-mail detailing your needs for a quote.

Current API version: 1.14

Use of the API requires authentication with your API key. Your key is displayed in the right column in your dashboard. If you do not yet have an account, please register for a free account.

Add key=<my_api_key> to all requests.

Browshot uses a REST API. Requests can be made with GET or POST commands to https://api.browshot.com/. All server replies are in JSON format.

Valid requests get a 200 OK server response. If the request is malformed, the server replies with a 403 error.

All API updates, library updates, and maintenance windows are announced on our blog, Browshot Service. We recommend that you subscribe to the blog RSS feed to get the latest news.

Libraries

Several open-source libraries are available to interact with the Browshot API in Perl, PHP, Python, Ruby, C#, etc.

Command line

You can request screenshots and retrieve thumbnails from the command line on Linux, Mac OS X or BSD using wget, curl, fetch, etc.

Simple API

The simple API is easier to use than the complete API, but it is also slower.

Request

Retrieve real-time screenshots with one request.

Retrieve a screenshot for the page http://mobilito.net/:

https://api.browshot.com/api/v1/simple?url=http://mobilito.net/&instance_id=12&key=my_api_key

Note: make sure you follow all 302/307 HTTP redirections. Since some pages may take 2 minutes to load, Browshot will send redirections to avoid HTTP timeouts.

IMPORTANT: if no instance_id is specified, the free instance #12 is used by default. Remember that you can only do 100 free screenshots per month. To used a premium instance, use instance_id=65 for example.

You can add any of the arguments that is supported by /api/v1/screenshot/create and Thumbnails. For example, to get a 640x480 thumbnail, use:

https://api.browshot.com/api/v1/simple?url=http://mobilito.net/&instance_id=12&width=640&height=480&key=my_api_key

Response

The status of the screenshot is described by the HTTP response code:

  • 200: successful, the response body contains the screenshot or thumbnail (PNG).
  • 404 Not Found: the screenshot could not be performed (page did not load, domain is not reachable, etc.). The response body contains the default image not-found.png. The description of the error is included in the X-Error HTTP response header.
  • 400: the request is invalid. You may have an invalid key, or invalid URL, etc. The description of the error is included in the X-Error HTTP response header.
  • 302: the screenshot is in progress, follow the redirection.

Complete API

Screenshot API

You can request screenshots from a specific instance, query their status and download the screenshots and/or thumbnails.

/api/v1/screenshot/create (update 1.14)

Screenshots requests to private and shared instances require a positive balance.

Request

Required parameters:

  • url: URL of the page to get a screenshot for
  • instance_id: instance ID to use

 

Common parameters:

  • size: screenshot size: "screen" (default) or "page"
  • cache: use a previous screenshot (same URL, same instance) if it was done within <cache_value> seconds. The default value is 24hours. Specify cache=0 if you want a new screenshot.
  • delay=0-10 (default: 5): number of seconds to wait after the page has loaded. This is used to let JavaScript run longer before taking the screenshot. Use delay=0 to take screenshots faster.
  • flash_delay=0-10 (default: 10): number of seconds to wait after the page has loaded if Flash elements are present. Use flash_delay=0 to take screenshots faster.

 

Optional parameters:

Hosting: You can get your screenshots and thumbnails hosted automatically on S3/Browshot/CDN with these additional parameters:

  • hosting: hosting option: s3 or browshot
  • hosting_height (optional): maximum width of the thumbnail to host
  • hosting_width (optional): maximum height of the thumbnail to host
  • hosting_scale (optional): scale of the thumbnail to host
  • hosting_bucket (required for S3): S3 bucket to upload the screenshot or thumbnail
  • hosting_file (optional, for S3 only): file name to use

If the screenshot is successful, the thumbnail or screenshot will be automatically hosted, there is no need to call screenshot/host.

Multiple screenshots: (new 1.14) You can take multiple screenshots of the same page at a specific interval with these additional parameters:

  • shots (1-3, default: 1): take 2 or 3 screenshots of the same page. This costs 1 credit.
  • shot_interval (1-10, default: 5): number of seconds between 2 screenshots

The priority is assigned automatically for public and shared instances: 1 for highest, 3 for lowest. Priority is given to accounts with fewer screenshots in processing state. The ratio of screenshots processed is about 4 priority 1, 2 priority 2 and 1 priority 3 (this may change in the future).

IMPORTANT: Remember that you can only do 100 free screenshots per month. To used a premium instance, use instance_id=65 for example.

Examples

https://api.browshot.com/api/v1/screenshot/create?url=http://www.google.com/&instance_id=3&size=screen&cache=0&key=my_api_key
Response
Error:
{
	  "error": "Wrong URL format",
	  "status": "error",
	  "priority": "1",
	  "cost": "0"
	  }
{
	  "error": "No free screenshots available",
	  "status": "error",
	  "priority": "1",
	  "cost": "0"
	  }
Request accepted
{
	  "id": "12589",
	  "status": "in_queue",
	  "priority": "2"
	  }
Screenshot found in cache
{
	  "id": "12589",
	  "status": "finished",
	  "screenshot_url": "https://www.browshot.com/screenshot/image/12589?scale=1&key=my_api_key",
	  "priority": "3",
	  "url": "http://www.google.com/",
	  "size": "screen",
	  "width": "1024",
	  "height": "768",
	  "request_time": "1312106111",
	  "started": "1312258803994",
	  "load": "1312258829461",
	  "content": "1312258829661",
	  "finished": "1312258829681",
	  "instance_id": "10",
	  "response_code": "200",
	  "final_url": "http://www.google.com/",
	  "content_type":"text/html",
	  "scale": "1",
	  "cost": "0",
	  "referer": "http://www.google.com/",
	  "post_data": "",
	  "cookie": "",
	  "delay": "5",
	  "flash_delay": "10",
	  "script": "",
	  "shared_url": "",
	  "details": 2,
	  "shots": 1,
	  "shot_interval": 5
	  }
  • id: screenshot ID
  • status: status of the request: "in_queue", "processing", "finished", "error"
  • screenshot_url: URL to download the screenshot
  • error: description of the problem that occurred
  • priority: priority given to the screenshot: high (1) to low (3)
  • url: original URL requested
  • size: screenshot size requested
  • width: screenshot width
  • height: screenshot height
  • final_url: URL of the screenshot (redirections can occur)
  • scale: image scale. Always 1 for desktop browsers; mobiles may change the scale (zoom in or zoom out) to fit the page on the screen
  • instance_id instance ID used for the screenshot
  • cost: number of credits spent for the screenshot
  • referer: custom referrer used (see Custom POST Data, Referer and Cookie)
  • post_data: POST data sent (see Custom POST Data, Referer and Cookie)
  • cookie custom cookie used (see Custom POST Data, Referer and Cookie)
  • delay: number of seconds to wait after page load
  • flash_delay: number of seconds to wait after page load if Flash elements are present
  • details=0-3 (optional, default: 2): level of details about the screenshot and the page.
  • script: URL of optional javascript file executed after the page load event

 

If details=1, additional information is sent:

  • response_code: HTTP response code for the main page (200, 404, 403, etc.)
  • content_type: content-type sent by the server (text/html, text/plain, image/jpeg, etc.)

 

If details=2, additional information is sent:

  • started: time of processing (UNIX timestamp)
  • finished: time of screenshot completed (UNIX timestamp)
  • load: time the page was loaded (UNIX timestamp, 0 if unknown)
  • request_time: time of request (UNIX timestamp) for the time of request
  • content: time the content was loaded (UNIX timestamp, 0 if unknown)

 

If details=3, and screenshot/create included details=3, additional information is sent:

  • images: list of absolute URLs of images included on the page
  • scripts: list of absolute URLs of external scripts included on the page
  • stylesheets: list of absolute URLs of external style sheets included on the page
  • embeds: list of absolute URLs of embed included on the page
  • applets: list of absolute URLs of applets included on the page
  • iframes: list of absolute URLs of frames included on the page

/api/v1/screenshot/multiple (new 1.13)

Request multiple screenshots in one API call.

Request

Parameters:

  • url: URL of the page to get a screenshot for. You can specify multiple url parameters (up to 10).
  • instance_id (optional, default: 12): instance ID to use. You can specify multiple instance_id parameters (up to 10).

The API call accepts all the parameters supported by screenshot/create.

You can specify up to 10 URLs and 10 instances for a total of 100 screenshots in one API call.

Examples

Request screenshots for 2 URLs with one instance:

https://api.browshot.com/api/v1/screenshot/create?url=http://www.google.com/&url=http://www.google.com/&instance_id=65&key=my_api_key

Request screenshots for 2 URLs with 2 instances (4 screenshots in total):

https://api.browshot.com/api/v1/screenshot/create?url=http://www.google.com/&url=http://www.google.com/&instance_id=65&instance_id=22&key=my_api_key
Response

The response format is the same as returned by screenshot/list.

/api/v1/screenshot/info

Once a screenshot has been requested, its status must be checked until it is either "error" or "finished".

Request

Parameters:

  • id: screenshot ID received from /api/v1/screenshot/create
  • details=0-3 (optional, default: 2): level of details about the screenshot and the page.

Example

https://api.browshot.com/api/v1/screenshot/info?id=12589&key=my_api_key
Response
Error:
{
	  "id": 12589,
	  "status": "error",
	  "screenshot_url": "https://www.browshot.com/screenshot/image/12589?scale=1&key=my_api_key",
	  "priority": "2",
	  "url": "http://www.google.com/",
	  "size": "screen",
	  "width": "1024",
	  "height": "768",
	  "request_time": "1312106111",
	  "started": "1312258803994",
	  "load": "0",
	  "content": "0",
	  "finished": "1312258829681",
	  "instance_id": "10",
	  "response_code": "",
	  "final_url": "",
	  "content_type":"",
	  "scale":"1",
	  "cost": "0",
	  "referer": "",
	  "post_data": "",
	  "cookie: "",
	  "delay": "5",
	  "flash_delay": "10",
	  "script": "",
	  "shared_url": "",
	  "details": 2
	  }
{
	  "id": "12589",
	  "status": "error",
	  "screenshot_url": "",
	  "priority": "3"
	  }
Success
{
	  "id": "12589",
	  "status": "finished",
	  "screenshot_url": "https://www.browshot.com/screenshot/image/12589?scale=1&key=my_api_key",
	  "priority": "12",
	  "url": "http://www.google.com/",
	  "size": "screen",
	  "width": "1024",
	  "height": "768",
	  "request_time": "1312106111",
	  "started": "1312258803994",
	  "load": "1312258829461",
	  "content": "1312258829661",
	  "finished": "1312258829681",
	  "instance_id": "10",
	  "response_code": "200",
	  "final_url": "http://www.google.com/",
	  "content_type":"text/html",
	  "scale": "1",
	  "cost": "0",
	  "referer": "",
	  "post_data": "foo=bar",
	  "cookie": "",
	  "delay": "5",
	  "flash_delay": "10",
	  "script": "",
	  "shared_url": "",
	  "details": 2
	  }
Screenshot not ready
{
	  "id": "12589",
	  "status": "in_queue",
	  "screenshot_url": "",
	  "cost": "0"
	  }
  • id: screenshot ID
  • status: status of the request: "in_queue", "processing", "finished", "error"
  • screenshot_url: URL to download the screenshot
  • error: description of the problem that occurred
  • priority: priority given to the screenshot: high (1) to low (3)
  • url: original URL requested
  • size: screenshot size requested
  • width: screenshot width
  • height: screenshot height
  • final_url: URL of the screenshot (redirections can occur)
  • scale: image scale. Always 1 for desktop browsers; mobiles may change the scale (zoom in or zoom out) to fit the page on the screen
  • instance_id instance ID used for the screenshot
  • cost: number of credits spent for the screenshot
  • referer: custom referrer used (see Custom POST Data, Referer and Cookie)
  • post_data: POST data sent (see Custom POST Data, Referer and Cookie)
  • cookie: custom cookie used (see Custom POST Data, Referer and Cookie)
  • delay: number of seconds to wait after page load
  • flash_delay: number of seconds to wait after page load if Flash elements are present
  • details=0-3 (optional, default: 2): level of details about the screenshot and the page.
  • script: URL of optional javascript file executed after the page load event
  • shared_url: if the screenshot was shared, show the public URL

Hosting: If the screenshot was set to be hosted, or if screenshot/host was called, the response will show the hosting information:

{
"hosting":[
    {
     "status":"finished",
     "url":"http://browshot.org/static/screenshots/1055447.png",
     "hosting":"browshot"
    }
]
  • status: status of the request: "error", "finished"
  • url: URL to the hosted screenshot or thumbnail
  • hosting: hosting option chosen
  • width: thumbnail width specified (if any)
  • height: thumbnail height specified (if any)
  • scale: thumbnail scale specified (if any)
  • bucket: bucket specified (S3 only)
  • file: file name specified (if any, S3 only)

 

If details=1, additional information is sent:

  • response_code: HTTP response code for the main page (200, 404, 403, etc.)
  • content_type: content-type sent by the server (text/html, text/plain, image/jpeg, etc.)

 

If details=2, additional information is sent:

  • started: time of processing (UNIX timestamp)
  • finished: time of screenshot completed (UNIX timestamp)
  • load: time the page was loaded (UNIX timestamp, 0 if unknown)
  • request_time: time of request (UNIX timestamp) for the time of request
  • content: time the content was loaded (UNIX timestamp, 0 if unknown)

 

If details=3, additional information is sent:

  • images: list of absolute URLs of images included on the page
  • scripts: list of absolute URLs of external scripts included on the page
  • stylesheets: list of absolute URLs of external style sheets included on the page
  • embeds: list of absolute URLs of embed included on the page
  • applets: list of absolute URLs of applets included on the page
  • iframes: list of absolute URLs of frames included on the page

/api/v1/screenshot/list

Get information about the last 100 screenshots requested.

Request

Parameters:

  • limit (optional, default 100, maximum: 1,000): number of screenshots' information to return
  • status (optional): get list of screenshot in a given status (error, finished, in_process)

Example

https://api.browshot.com/api/v1/screenshot/list?limit=50&key=my_api_key
Response
{
		"52967":{
		    "priority":"1",
		    "status":"finished",
		    "screenshot_url":"https://www.browshot.com/screenshot/image/52967?scale=1&key=my_api_key",
		    "id":"52967",
		    "url": "http://www.google.com/",
		    "size": "screen",
		    "width": "1024",
		    "height": "768",
		    "request_time": "1312106111",
		    "started": "1312258803994",
		    "load": "1312258829461",
		    "content": "1312258829661",
		    "finished": "1312258829681",
		    "instance_id": "10",
		    "response_code": "200",
		    "final_url": "http://www.google.com/",
		    "content_type":"text/html",
		    "scale": "1",
		    "cost": "0",
		    "referer": "",
		    "post_data": "",
		    "cookie": "",
		    "delay": "5",
		    "flash_delay": "10",
		    "script": "",
		    "shared_url": ""
		},
		"52969":{
		    "priority":"1",
		    "status":"finished",
		    "screenshot_url":"https://www.browshot.com/screenshot/image/52969?scale=1&key=my_api_key",
		    "id":"52969",
		    "url": "http://www.google.com/",
		    "size": "screen",
		    "width": 1024,
		    "height": "768",
		    "request_time": "1312106111",
		    "started": "1312258803994",
		    "load": "1312258829461",
		    "content": "1312258829661",
		    "finished": "1312258829681",
		    "instance_id": "10",
		    "response_code": "200",
		    "final_url": "http://www.google.com/",
		    "content_type":"text/html",
		    "scale": "1",
		    "cost": "0",
		    "referer": "",
		    "post_data": "",
		    "cookie": "",
		    "delay": "5",
		    "flash_delay": "10",
		    "script": "",
		    "shared_url": ""
		},
		"52971":{
		    "priority":"1",
		    "status":"processing",
		    "screenshot_url":"https://www.browshot.com/screenshot/image/52971?scale=1&key=my_api_key",
		    "id":"52971",
		    "url": "http://www.google.com/",
		    "size": "screen",
		    "width": "1024",
		    "height": "768",
		    "request_time": "1312106111",
		    "started": "1312258803994",
		    "load": "1312258829461",
		    "content": "1312258829661",
		    "finished": "1312258829681",
		    "instance_id": "10",
		    "response_code": "200",
		    "final_url": "http://www.google.com/",
		    "content_type":"text/html",
		    "scale": "1",
		    "cost": "0",
		    "referer": "",
		    "post_data": "",
		    "cookie": "",
		    "delay": "5",
		    "flash_delay": "10",
		    "script": "",
		    "shared_url": ""
		},
		"52970":{
		    "priority":"1",
		    "status":"finished",
		    "screenshot_url":"https://www.browshot.com/screenshot/image/52970?scale=1&key=my_api_key",
		    "id":"52970",
		    "url": "http://www.google.com/",
		    "size": "screen",
		    "width": "1024",
		    "height": "768",
		    "request_time": "1312106111",
		    "started": "1312258803994",
		    "load": "1312258829461",
		    "content": "1312258829661",
		    "finished": "1312258829681",
		    "instance_id": "10",
		    "response_code": "200",
		    "final_url": "http://www.google.com/",
		    "content_type":"text/html",
		    "scale": "1",
		    "cost": "0",
		    "referer": "",
		    "post_data": "",
		    "cookie": "",
		    "delay": "5",
		    "flash_delay": "10",
		    "script": "",
		    "shared_url": ""
		},
		"52968":{
		    "priority":"1",
		    "status":"finished",
		    "screenshot_url":"https://www.browshot.com/screenshot/image/52968?scale=1&key=my_api_key",
		    "id":"52968",
		    "url": "http://www.google.com/",
		    "size": "screen",
		    "width": "1024",
		    "height": "768",
		    "request_time": "1312106111",
		    "started": "1312258803994",
		    "load": "1312258829461",
		    "content": "1312258829661",
		    "finished": "1312258829681",
		    "instance_id": "10",
		    "response_code": "200",
		    "final_url": "http://www.google.com/",
		    "content_type":"text/html",
		    "scale": "1",
		    "cost": "0",
		    "referer": "",
		    "post_data": "",
		    "cookie": "",
		    "delay": "5",
		    "flash_delay": "10",
		    "script": "",
		    "shared_url": ""
		}}

The key is the screenshot ID

  • id: screenshot ID
  • status: status of the request: "in_queue", "processing", "finished", "error"
  • screenshot_url: URL to download the screenshot
  • error: description of the problem that occurred
  • priority: priority given to the screenshot: high (1) to low (3)
  • url: original URL requested
  • size: screenshot size requested
  • width: screenshot width
  • height: screenshot height
  • final_url: URL of the screenshot (redirections can occur)
  • scale: image scale. Always 1 for Desktop browsers, Mobiles may change the scale (zoom in or zoom out) to fit the page on the screen
  • instance_id instance ID used for the screenshot
  • cost: number of credits spent for the screenshot
  • referer: custom referrer used (see Custom POST Data, Referer and Cookie)
  • post_data: POST data sent (see Custom POST Data, Referer and Cookie)
  • cookie: custom cookie used (see Custom POST Data, Referer and Cookie)
  • delay: number of seconds to wait after page load
  • flash_delay: number of seconds to wait after page load if Flash elements are present
  • details=0-3 (optional, default: 2) : level of details about the screenshot and the page.
  • script: URL of optional javascript file executed after the page load event
  • shared_url: if the screenshot was shared, show the public URL

 

Hosting: If the screenshot was set to be hosted, or if screenshot/host was called, the response will show the hosting information:

{
"hosting":[
    {
     "status":"finished",
     "url":"http://browshot.org/static/screenshots/1055447.png",
     "hosting":"browshot"
    }
]

 

If details=1, additional information is sent:

  • response_code: HTTP response code for the main page (200, 404, 403, etc.)
  • content_type: content-type sent by the server (text/html, text/plain, image/jpeg, etc.)

 

If details=2, additional information is sent:

  • started: time of processing (UNIX timestamp)
  • finished: time of screenshot completed (UNIX timestamp)
  • load: time the page was loaded (UNIX timestamp, 0 if unknown)
  • request_time: time of request (UNIX timestamp) for the time of request
  • content: time the content was loaded (UNIX timestamp, 0 if unknown)

 

If details=3, additional information is sent:

  • images: list of absolute URLs of images included on the page
  • scripts: list of absolute URLs of external scripts included on the page
  • stylesheets: list of absolute URLs of external style sheets included on the page
  • embeds: list of absolute URLs of embed included on the page
  • applets: list of absolute URLs of applets included on the page
  • iframes: list of absolute URLs of frames included on the page

/api/v1/screenshot/search

Search for screenshots of a specific URL.

Request

Parameters:

  • url: look for a string matching the URL requested.
  • limit (optional, default 50, maximum: 100): maximum number of screenshots' information to return
  • status (optional): get list of screenshot in a given status (error, finished, in_process)

Example

https://api.browshot.com/api/v1/screenshot/search?url=google&key=my_api_key
Response
{
		"52967":{
		    "priority":"1",
		    "status":"finished",
		    "screenshot_url":"https://www.browshot.com/screenshot/image/52967?scale=1&key=my_api_key",
		    "id":"52967",
		    "url": "http://www.google.com/",
		    "size": "screen",
		    "width": "1024",
		    "height": "768",
		    "request_time": "1312106111",
		    "started": "1312258803994",
		    "load": "1312258829461",
		    "content": "1312258829661",
		    "finished": "1312258829681",
		    "instance_id": "10",
		    "response_code": "200",
		    "final_url": "http://www.google.com/",
		    "content_type":"text/html",
		    "scale": "1",
		    "cost": "0",
		    "referer": "",
		    "post_data": "",
		    "cookie": "",
		    "delay": "5",
		    "flash_delay": "10",
		    "script": "",
		    "shared_url": ""
		},
		"52969":{
		    "priority":"1",
		    "status":"finished",
		    "screenshot_url":"https://www.browshot.com/screenshot/image/52969?scale=1&key=my_api_key",
		    "id":"52969",
		    "url": "http://www.google.org/",
		    "size": "screen",
		    "width": 1024,
		    "height": "768",
		    "request_time": "1312106111",
		    "started": "1312258803994",
		    "load": "1312258829461",
		    "content": "1312258829661",
		    "finished": "1312258829681",
		    "instance_id": "10",
		    "response_code": "200",
		    "final_url": "http://www.google.org/",
		    "content_type":"text/html",
		    "scale": "1",
		    "cost": "0",
		    "referer": "",
		    "post_data": "",
		    "cookie": "",
		    "delay": "5",
		    "flash_delay": "10",
		    "script": "",
		    "shared_url": ""
		},
		"52971":{
		    "priority":"1",
		    "status":"processing",
		    "screenshot_url":"https://www.browshot.com/screenshot/image/52971?scale=1&key=my_api_key",
		    "id":"52971",
		    "url": "http://www.google.de/",
		    "size": "screen",
		    "width": "1024",
		    "height": "768",
		    "request_time": "1312106111",
		    "started": "1312258803994",
		    "load": "1312258829461",
		    "content": "1312258829661",
		    "finished": "1312258829681",
		    "instance_id": "10",
		    "response_code": "200",
		    "final_url": "http://www.google.de/",
		    "content_type":"text/html",
		    "scale": "1",
		    "cost": "0",
		    "referer": "",
		    "post_data": "",
		    "cookie": "",
		    "delay": "5",
		    "flash_delay": "10",
		    "script": "",
		    "shared_url": ""
		},
		"52970":{
		    "priority":"1",
		    "status":"finished",
		    "screenshot_url":"https://www.browshot.com/screenshot/image/52970?scale=1&key=my_api_key",
		    "id":"52970",
		    "url": "http://www.google.fr/",
		    "size": "screen",
		    "width": "1024",
		    "height": "768",
		    "request_time": "1312106111",
		    "started": "1312258803994",
		    "load": "1312258829461",
		    "content": "1312258829661",
		    "finished": "1312258829681",
		    "instance_id": "10",
		    "response_code": "200",
		    "final_url": "http://www.google.fr/",
		    "content_type":"text/html",
		    "scale": "1",
		    "cost": "0",
		    "referer": "",
		    "post_data": "",
		    "cookie": "",
		    "delay": "5",
		    "flash_delay": "10",
		    "script": "",
		    "shared_url": ""
		},
		"52968":{
		    "priority":"1",
		    "status":"finished",
		    "screenshot_url":"https://www.browshot.com/screenshot/image/52968?scale=1&key=my_api_key",
		    "id":"52968",
		    "url": "http://www.google.com/",
		    "size": "screen",
		    "width": "1024",
		    "height": "768",
		    "request_time": "1312106111",
		    "started": "1312258803994",
		    "load": "1312258829461",
		    "content": "1312258829661",
		    "finished": "1312258829681",
		    "instance_id": "10",
		    "response_code": "200",
		    "final_url": "http://www.google.com/",
		    "content_type":"text/html",
		    "scale": "1",
		    "cost": "0",
		    "referer": "",
		    "post_data": "",
		    "cookie": "",
		    "delay": "5",
		    "flash_delay": "10",
		    "script": "",
		    "shared_url": ""
		}}

The key is the screenshot ID

  • id: screenshot ID
  • status: status of the request: "in_queue", "processing", "finished", "error"
  • screenshot_url: URL to download the screenshot
  • error: description of the problem that occurred
  • priority: priority given to the screenshot: high (1) to low (3)
  • url: original URL requested
  • size: screenshot size requested
  • width: screenshot width
  • height: screenshot height
  • final_url: URL of the screenshot (redirections can occur)
  • scale: image scale. Always 1 for Desktop browsers, Mobiles may change the scale (zoom in or zoom out) to fit the page on the screen
  • instance_id instance ID used for the screenshot
  • cost: number of credits spent for the screenshot
  • referer: custom referrer used (see Custom POST Data, Referer and Cookie)
  • post_data: POST data sent (see Custom POST Data, Referer and Cookie)
  • cookie: custom cookie used (see Custom POST Data, Referer and Cookie)
  • delay: number of seconds to wait after page load
  • flash_delay: number of seconds to wait after page load if Flash elements are present
  • details=0-3 (optional, default: 2) : level of details about the screenshot and the page.
  • script: URL of optional javascript file executed after the page load event
  • shared_url: if the screenshot was shared, show the public URL

/api/v1/screenshot/host (update 1.14)

You can host screenshots and thumbnails on your own S3 account or on Browshot (requires pre-approval before you can use them, please contact us).

Request

Parameters:

  • id: screenshot ID
  • hosting: hosting option: s3 or browshot
  • width (optional): width of the thumbnail
  • height (optional): height of the thumbnail
  • scale (optional): scale of the thumbnail
  • bucket (required with hosting=s3) S3 bucket to upload the screenshot or thumbnail
  • file (optional, used with hosting=s3) file name to use

If neither width, height and scale are not specified, the original screenshot is hosted.

Example

https://api.browshot.com/api/v1/screenshot/host?id=3965421&hosting=s3&bucket=my_browshot_bucket_name&key=my_api_key
Response

Error

An error is sent back if you do not have pre-approval for the feature, or if the screenshot failed, or if an error occurred during the S3 upload (bad bucket name, wrong ACLs, etc.), etc.

{
		"status": "error",
		"error" : "Invalid screenshot id",
		"id": 3965421
		}
{
		"status": "error",
		"error" : "Screenshot failed previously",
		"id": 3965421
		}
{
		"status": "error",
		"error" : "Screenshot failed previously",
		"id": 3965421
		}

Success
{
		"status": "ok",
		"url": "http://aws.amazon.com/my_browshot_bucket_name/3965421-640-480.png",
		"id": 3965421
		}
  • id: screenshot ID
  • status: status of the request: "error", "ok" or "in_queue"
  • url: URL to the hosted screenshot or thumbnail

You will need our S3 account information to let us upload screenshots and thumbnails to your S3 buckets. Please contact us about S3 hosting.

/api/v1/screenshot/thumbnail (update 1.14)

Unlike the other API calls, this API sends back the thumbnail as a PNG file, not JSON. The HTTP response code indicates whether the screenshot was successful (200), or incomplete (404) or failed (404). If the screenshot failed or is not finished, a default image "Not found" is sent.

You can crop your screenshots. The crop is done first, then the thumbnail. You can take a 1024x768 screenshot, crop it to 768x768, and get it scaled down to 300x300.

Request

Parameters:

  • id: screenshot ID
  • width (optional): width of the thumbnail
  • height (optional): height of the thumbnail
  • scale (optional): scale of the thumbnail
  • zoom=<1-100> (optional): zoom 1 to 100 percent
  • ratio=<fit|fill> (optional, default: fit). Use fit to keep the original page ration, and fill to get a thumbnail for the exact width and height specified.
  • left (optional, default: 0): left edge of the area to be cropped
  • right (optional, default: screenshot's width): right edge of the area to be cropped
  • top (optional, default: 0): top edge of the area to be cropped
  • bottom (optional, default: screenshot's height): right edge of the area to be cropped
  • format (jpeg or png, default: png): (update 1.14) image as PNG or JPEG
  • shot (1-3, default: 1): (update 1.14) get the second or third screenshot if multiple screenshots were requested

If you provide both width and height, you need to specify the ratio: fit to keep the original width/height ratio (the thumbnail might be smaller than the specified width and height), or fill to crop the image if necessary.

Examples

Get a thumbnail at 1/3 (33%) of the original:

https://api.browshot.com/api/v1/screenshot/thumbnail?id=3965421&zoom=33&key=my_api_key

Get a thumbnail with a height of 100 pixels at most:

https://api.browshot.com/api/v1/screenshot/thumbnail?id=3965421&height=100&key=my_api_key

Get a thumbnail of 200 by 100 pixels at most:

https://api.browshot.com/api/v1/screenshot/thumbnail?id=3965421&height=100&width=200&ratio=fit&key=my_api_key

Crop the screenshot to 768x768, scale it to a 300x300 thumbnail:

https://api.browshot.com/api/v1/screenshot/thumbnail?id=3965421&right=300&bottom=300&height=100&width=200&ratio=fit&key=my_api_key

/api/v1/screenshot/share

You can make your screenshots public, add notes, and share it with your friends and colleagues. Only screenshots which are successfully completed can be shared.

Request

Parameters:

  • id: screenshot ID
  • note (optional): note to add on the sharing page

 

Examples
https://api.browshot.com/api/v1/screenshot/share?id=3965421&note=this+is+my+screenshot&key=my_api_key
Response

Error
{
		"status": "error",
		"error" : "Invalid screenshot id",
		"id": 3965421
		}
Success
{
		"status": "ok",
		"url": "https://browshot.com/share/U6uVs0VysLbf9VCms",
		"id": 3965421
		}
  • id: screenshot ID
  • status: status of the request: "error", "ok"
  • url: URL to the sharing page

/api/v1/screenshot/delete

You can delete details of your screenshots to remove any confidential information.

Request

Parameters:

  • id: screenshot ID
  • data (optional): data to remove. You can specify multiple of them (separated by a ,):
    • image (default): image file (screenshot and thumbnails)
    • url: url requested
    • metadata: time added, time finished, post data, cookie and referer used for the screenshot
    • all: all data above

     

    Examples
    https://api.browshot.com/api/v1/screenshot/delete?id=3965421&data=image,metadata&key=my_api_key
    Response

    Error
    {
    		"status": "error",
    		"error" : "Invalid screenshot id",
    		"id": 3965421
    		}
    Success
    {
    		"status": "ok",
    		"id": 3965421
    		}
    • id: screenshot ID
    • status: status of the request: "error", "ok"

    /api/v1/screenshot/html (new 1.13)

    Retrieve the HTML code of the rendered page. This API call should be used when html=1 was specified in the screenshot request.

    Request

    Parameters:

    • id: screenshot ID

    This API calls returns the HTML of the rendered page when successful, or an empty body with a 404 HTTP status code in case of failure.

    /api/v1/batch/create (new 1.14)

    Get hundreds or thousands of screenshots from a text file. You can use this API call or the dashboard.

    Unlike the other API calls, you must issue a POST request with the Content-Type "multipart/form-data" in order to upload the text file.

    The text file must contain the list of URLs to request, 1 URL per line. Failed screenshots will be tried up to 3 times before giving up.

    Request

    Required parameters:

    • url: URL of the page to get a screenshot for
    • instance_id: instance ID to use
    • file: file content

     

    Optional parameters:

    • size: screenshot size: "screen" (default) or "page"
    • name: name of the batch
    • width: screenshot width
    • height: screenshot height
    • format (jpeg or png, default: png): image as PNG or JPEG
    • delay=0-10 (default: 5): number of seconds to wait after the page has loaded. This is used to let JavaScript run longer before taking the screenshot. Use delay=0 to take screenshots faster.
    • flash_delay=0-10 (default: 10): number of seconds to wait after the page has loaded if Flash elements are present. Use flash_delay=0 to take screenshots faster.
    • referer ( paid screenshots only): use a custom referrer (see Custom POST Data, Referer and Cookie)
    • post_data (paid screenshots only): send a POST requests with post_data, useful for filling out forms (see Custom POST Data, Referer and Cookie)
    • cookie (paid screenshots only): set a cookie for the URL requested (see Custom POST Data, Referer and Cookie)
    • script: URL of javascript file to execute after the page load event.
    • details=1-3 ( default: 2): level of information available with screenshot/info.
    • html=0,1 (default: 0): saves the HTML of the rendered page which can be retrieved by the API call screenshot/html. This feature costs 1 credit per screenshot.
    • shots (1-3, default: 1): take 2 or 3 screenshots of the same page. This costs 1 credit.
    • shot_interval (1-10, default: 5): number of seconds between 2 screenshots

     

    Response

    Error
    {
    		"status": "error",
    		"error" : "Missing file"
    		}
    Success
    {
    		"status": "in_queue",
    		"id": 5
    		}

    /api/v1/batch/info (new 1.14)

    Get the status of a batch requested through the API or through the dashboard.

    Request

    Parameters:

    • id: batch ID

     

    Response

    Error
    {
    		"status": "error",
    		"error" : "Wrong batch ID"
    		}
    Success
    {
    		"status": "in_queue",
    		"id": 5
    		}
    {
    		"status": "in_process",
    		"id": 5,
    		"started":  1312106111,
    		"finished":  0,
    		"count":  10000,
    		"processed": 523,
    		"failed": 7
    		}
    • status: status of the request: "in_queue", "processing", "finished", "error"
    • id: batch ID
    • started: time of processing (UNIX timestamp)
    • finished: time of batch completed (UNIX timestamp)
    • count: number of unique URLs in the batch
    • processed: number of screenshots finished
    • failed: number of screenshots failed

    Account API

    /api/v1/account/info (update 1.14)

    Get information about your account.

    Request

    Parameters:

    • details (optional, 1-3, default: 1): level of information returned

    Example

    https://api.browshot.com/api/v1/account/info?details=3&key=my_api_key
    Response
    {
    		"balance":"0",
    		"instances":[],
    		"screenshots":[
    		    {"width":"1024",
    		    "priority":"1",
    		    "status":"finished",
    		    "content":1320989264533,
    		    "size":"screen",
    		    "url":"http://www.free.fr/",
    		    "id":"10",
    		    "screenshot_url":"http://127.0.0.1:3000/screenshot/image/10?key=my_api_key",
    		    "load":1320989268347,
    		    "request_time":"1320989261",
    		    "instance_id":"12",
    		    "height":"768",
    		    "response_code":200,
    		    "final_url":"http://www.free.fr/adsl/index.html",
    		    "content_type":"text/html",
    		    "scale":1,
    		    "started":1320989261960,
    		    "finished":1320989273508
    		    }
    		],
    		"browsers":[
    		    {"appversion":"",
    		    "user_agent":"custom",
    		    "name":"Custom browser",
    		    "javascript":"0",
    		    "mobile":0,
    		    "appname":"",
    		    "vendorsub":"",
    		    "appcodename":"",
    		    "platform":"",
    		    "vendor":"",
    		    "flash":"0"
    		    }
    		]
    		},
    		"free_screenshots_left": "85",
    		"private_instances": "0",
    		"hosting_browshot": "0"
    }
    • balance: number of credits left on your account
    • free_screenshots_left: number of free screenshots available for the current month
    • private_instances: 1 is your account is authorized to create and use private instances, 0 otherwise (default)
    • hosting_browshot: 1 is your account is authorized to request hosting on Browshot, 0 otherwise (default)

    If details=2, additional information is sent:

    If details=3, additional information is sent:

     

    Instance API

    You can get the list of instances available.
    (The creation of new private instances is available to some users only, please contact us if you think you need private instances.)

    /api/v1/instance/list

    Request

    No parameters.

    Example:

    https://api.browshot.com/api/v1/instance/list?key=my_api_key
    Response

    The instances are divided into 3 types:

    • free: free instances available to all registered users.
    • shared: instances available to all registered users with a positive balance. Each screenshot requested for these instances has a cost.
    • private: custom instances created for a specific user. Each screenshot requested for these instances has a cost.

    Example:

    {"shared":[],
    		"free":[{
    		    "width":"1024",
    		    "height":"768",
    		    "browser":{
    		        "id": "3",
    		        "name":"Internet Explorer 8",
    		        "javascript":"1",
    		        "mobile":"0",
    		        "flash":"1"
    		    },
    		    "type":"public",
    		    "id":"11",
    		    "load":"0.5",
    		    "screenshot_cost":"1",
    		    "country":"USA"
    		}],
    		"private":[]
    		}
    • id: instance ID (required to requests screenshots)
    • width: screen width in pixels
    • height: screen height in pixels
    • load: instance load
      • < 1: new screenshot requests will be processed immediately
      • 1-2: new screenshot requests will be processed in about two minutes
      • 2-3: new screenshot requests will be processed in about four minutes
      • 3-4: new screenshot requests will be processed in about six minutes
      • etc.
    • browser: virtual browser features
      • id: browser ID
      • name: browser name and version: Internet Explorer 8, Opera 10.51, Firefox 4.0.1, etc.
      • javascript: JavaScript support: 1 if enabled, 0 if disabled
      • flash: Flash support: 1 if enabled, 0 if disabled
      • mobile: Mobile browser: 1 if true, 0 if false
    • type: public, shared or private
    • screenshot_cost: number of credits for each screenshot
    • country: instance's country of origin

    /api/v1/instance/info

    Request

    Parameters:

    • id: instance ID

    Example:

    https://api.browshot.com/api/v1/instance/info?id=3&key=my_api_key
    Response
    Error
    {
    		"error": "Instance not found",
    		"status": "error"
    		}
    Instance found
    {
    		"width":"1024",
    		"height":"768",
    		"browser":{
    		    "id": "3",
    		    "name":"Internet Explorer 8",
    		    "javascript":"1",
    		    "mobile":"0",
    		    "flash":"1"
    		},
    		"type":"public",
    		"id":"11",
    		"load":"0.5",
    		"active":"1",
    		"screenshot_cost":"1",
    		"country":"Australia"
    		}
    • id: instance ID (required to requests screenshots)
    • width: screen width in pixels
    • height: screen height in pixels
    • load: instance load
      • < 1: new screenshot requests will be processed immediately
      • 1-2: new screenshot requests will be processed in about two minutes
      • 2-3: new screenshot requests will be processed in about four minutes
      • 3-4: new screenshot requests will be processed in about six minutes
      • etc.
    • browser: virtual browser features
      • id: browser ID
      • name: browser name and version: Internet Explorer 8, Opera 10.51, Firefox 4.0.1, etc.
      • javascript: JavaScript support: 1 if enabled, 0 if disabled
      • flash: Flash support: 1 if enabled, 0 if disabled
      • mobile: Mobile browser: 1 if true, 0 if false
    • type: public, shared or private
    • screenshot_cost: number of credits for each screenshot
    • country: instance's country of origin

    Browser API

    Each instance can use a different user agent.

    /api/v1/browser/list

    List of all predefined web browsers. You can get the list of predefined browsers and create new browsers for your private instances.

    Request

    No parameters.

    Example:

    https://api.browshot.com/api/v1/browser/list?key=my_api_key
    Response
    {
    		"6":{
    		    "name":"Yahoo Slurp",
    		    "user_agent":"Mozilla/5.0 (compatible; Yahoo! Slurp; http://help.yahoo.com/help/us/ysearch/slurp)",
    		    "appname":"",
    		    "vendorsub":"",
    		    "appcodename":"",
    		    "platform":"",
    		    "vendor":"",
    		    "appversion":"",
    		    "javascript":"0",
    		    "mobile":"0",
    		    "flash":"0"
    		},
    		"11":{
    		    "name":"Android Nesus S",
    		    "user_agent":"Mozilla/5.0 (Linux; U; Android 2.3.4; en-us; Nexus S Build/GRJ22) AppleWebKit/533.1 (KHTML, like Gecko) Version/4.0 Mobile Safari/533.1",
    		    "appname":"",
    		    "vendorsub":"",
    		    "appcodename":"",
    		    "platform":"",
    		    "vendor":"",
    		    "appversion":"",
    		    "flash":"0",
    		    "javascript":"1",
    		    "mobile":"1"
    		}
    		}

    The key is the browser ID (same ID as in /api/v1/instance/list)

    • name: browser name and version: Internet Explorer 8, Opera 10.51, Firefox 4.0.1, etc.
    • user_agent: browser user agent string
    • appname, vendorsub, appcodename, platform, vendor, appversion: user agent identifiers
    • javascript: JavaScript support: 1 if enabled, 0 if disabled
    • flash: Flash support: 1 if enabled, 0 if disabled
    • mobile: Mobile browser: 1 if true, 0 if false

    /api/v1/browser/info

    Request

    Parameters

    • id: browser ID

    Example:

    https://api.browshot.com/api/v1/browser/info?id=6&key=my_api_key
    Response
    Error
    {
    		"error": "Browser not found",
    		"status": "error"
    		}
    Browser found
    {
    		    "name":"Yahoo Slurp",
    		    "user_agent":"Mozilla/5.0 (compatible; Yahoo! Slurp; http://help.yahoo.com/help/us/ysearch/slurp)",
    		    "appname":"",
    		    "vendorsub":"",
    		    "appcodename":"",
    		    "platform":"",
    		    "vendor":"",
    		    "appversion":"",
    		    "javascript":"0",
    		    "mobile":"0",
    		    "flash":"0"
    		}
    • name: browser name and version: Internet Explorer 8, Opera 10.51, Firefox 4.0.1, etc.
    • user_agent: browser user agent string
    • appname, vendorsub, appcodename, platform, vendor, appversion: user agent identifiers
    • javascript: JavaScript support: 1 if enabled, 0 if disabled
    • flash: Flash support: 1 if enabled, 0 if disabled
    • mobile: Mobile browser: 1 if true, 0 if false




close

Sign up for a free account