We can write custom code for you. Send us an e-mail detailing your needs for a quote.
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.
Several open-source libraries are available to interact with the Browshot API in Perl, PHP, Python, Ruby, C#, etc.
You can request screenshots and retrieve thumbnails from the command line on Linux, Mac OS X or BSD using wget, curl, fetch, etc.
The simple API is easier to use than the complete API, but it is also slower.
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_keyNote: 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_keyThe status of the screenshot is described by the HTTP response code:
You can request screenshots from a specific instance, query their status and download the screenshots and/or thumbnails.
Screenshots requests to private and shared instances require a positive balance.
Parameters:
Hosting:(new 1.11) You can get your screenshots and thumbnails hosted automatically on S3/Browshot/CDN with these additional parameters:
If the screenshot is successful, the thumbnail or screenshot will be automatically hosted, there is no need to call screenshot/host.
If both the screen and instance_id are used, screen is ignored
If screen is used, a free instance matching the screen resolution is used. If no match is found, a random free instance is used.
If both the screen and instance_id are omitted, a random free instance is used.
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: 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.
Examples
https://api.browshot.com/api/v1/screenshot/create?url=http://www.google.com/&instance_id=3&size=screen&cache=0&key=my_api_keyhttps://api.browshot.com/api/v1/screenshot/create?url=http://www.browshot.com/&screen=1200x800&size=page&key=my_api_key
{
"error": "Wrong URL format",
"status": "error",
"priority": "1",
"cost": "0"
}{
"error": "No free screenshots available",
"status": "error",
"priority": "1",
"cost": "0"
}{
"id": "12589",
"status": "in_queue",
"priority": "2"
}{
"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": ""
}
If details=1, additional information is sent:
If details=2, additional information is sent:
If details=3, additional information is sent:
Once a screenshot has been requested, its status must be checked until it is either "error" or "finished".
Parameter:
Example
https://api.browshot.com/api/v1/screenshot/info?id=12589&key=my_api_key{
"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": ""
}{
"id": "12589",
"status": "error",
"screenshot_url": "",
"priority": "3"
}{
"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": ""
}{
"id": "12589",
"status": "in_queue",
"screenshot_url": "",
"cost": "0"
}
Hosting:(new 1.11) 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:
If details=2, additional information is sent:
If details=3, additional information is sent:
Get information about the last 100 screenshots requested.
Parameter:
Example
https://api.browshot.com/api/v1/screenshot/list?limit=50&key=my_api_key{
"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
Hosting:(new 1.11) 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:
If details=2, additional information is sent:
If details=3, additional information is sent:
You can host screenshots and thumbnails on your own S3 account, on our CDN server, or on Browshot. These features require pre-approval before you can use them, please contact us.
Parameter:
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
An error is sent back if you do not have preapproval 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
}
{
"status": "ok",
"url": "http://aws.amazon.com/my_browshot_bucket_name/3965421-640-480.png",
"id": 3965421
}
You will need our S3 account information to let us upload screenshots and thumbnails to your S3 buckets. Please contact us about S3 hosting.
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.
Update 1.10: you can now crop your screenshots. The crop is done first, then the thumbnail. You can take a 1024x738 screenshot, crop it to 7168x768, and get it scaled down to 300x300.
Parameters:
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.
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_keyGet 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_keyGet 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_keyCrop 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_keyYou can make your screenshots public, add notes, and share it with your friends and colleagues. Only screenshots which are successfully completed can be shared.
Parameters:
https://api.browshot.com/api/v1/screenshot/share?id=3965421¬e=this+is+my+screenshot&key=my_api_key
{
"status": "error",
"error" : "Invalid screenshot id",
"id": 3965421
}{
"status": "ok",
"url": "https://browshot.com/share/U6uVs0VysLbf9VCms",
"id": 3965421
}You can delete details of your screenshots to remove any confidential information.
Parameters:
https://api.browshot.com/api/v1/screenshot/delete?id=3965421&data=image,metadata&key=my_api_key
{
"status": "error",
"error" : "Invalid screenshot id",
"id": 3965421
}{
"status": "ok",
"id": 3965421
}Get information about your account.
No parameters
Example
https://api.browshot.com/api/v1/account/info?key=my_api_key{
"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_s3": 0,
"hosting_cdn": "0",
"hosting_browshot": "0"
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.)
No parameters.
Example:
https://api.browshot.com/api/v1/instance/list?key=my_api_keyThe instances are divided into 3 types:
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":[]
}Parameters:
Example:
https://api.browshot.com/api/v1/instance/info?id=3&key=my_api_key{
"error": "Instance not found",
"status": "error"
}{
"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"
}The creation of private instances is reserved to some users only, please contact us if you think you need private instances.
Parameters:
Example:
https://api.browshot.com/api/v1/instance/create?width=1600&height=1200&browser_id=3&key=my_api_key{
"error": "Unknown browser ID.",
}{
"error": "You are not allowed to create private instances.",
}{
"width":"1600",
"height":"1200",
"browser":{
"id": "3",
"name":"Internet Explorer 8",
"javascript":"1",
"mobile":"0",
"flash":"1"
},
"type":"private",
"id":"15",
"load":"0",
"active":"1",
"screenshot_cost":"0",
"country":"USA"
}Each instance can use a different user agent.
List of all predefined web browsers. You can get the list of predefined browsers and create new browsers for your private instances.
No parameters.
Example:
https://api.browshot.com/api/v1/browser/list?key=my_api_key{
"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)
Parameters
Example:
https://api.browshot.com/api/v1/browser/info?id=6&key=my_api_key{
"error": "Browser not found",
"status": "error"
}{
"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"
}The creation of browsers is reserved to some users only, please contact us if you think you need private instances with custom browsers.
Parameters
Example:
https://api.browshot.com/api/v1/browser/info?user_agent=my+custom+agent&mobile=0&flash=1&javascript=1&key=my_api_key{
"error": "Browser not found",
"status": "error"
}{
"error": "You are not allowed to create custom browsers.",
"status": "error"
}{
"name":"Custom browser",
"user_agent":"my custom agent",
"appname":"",
"vendorsub":"",
"appcodename":"",
"platform":"",
"vendor":"",
"appversion":"",
"javascript":"1",
"mobile":"0",
"flash":"1"
}The key is the browser ID (same ID as in /api/v1/instance/list)