Read XL Bins API

You could now store up to 10MB of JSON files using the Create XL Bins API. You could read the XL Bins using the Read XL Bins API.

INFO The entire payload of the file you are reading will be sent in response, in the future, we may allow options to Read Stream or Download JSON file.

IMPORTANT XL Bins API is an Early Access Feature. It may change drastically over time or may get discontinued in the future. We would not recommend you to use this feature on Production until it graduates to a stable release in the future.



Disable Meta Data using Query Parameter instead of X-Bin-Meta header

Request Type


Request Headers

Below are the list of Accepted Request Headers if you are trying to Create a JSON record.

Request Header Value Required
Content-Type application/json Yes
X-Master-Key <API_KEY> Yes
X-Bin-Meta <true / false> No
Content-Type Required

Set the Content-Type header to application/json. This needs to be passed with every GET request you make on the Read XL Bins Route. Failing to pass this in the Header will result in an error.

INFO As of now, you could only fetch the entire body as JSON in response. In the future, we may make streaming of JSON & Download as other response options.

X-Master-Key Required

X-Master-Key is nothing but your Core API Access Key. You will need this Key to access mostly any API end-point on JSONBin. You could find the key on the API Keys page.

X-Bin-Meta Optional

You may pass X-Bin-Meta header with a value of false. Doing this will omit all the metadata of the bin and will simply return the data you have stored.

Code Samples

  • cURL
  • JavaScript (ES6)
  • Python 3
  • Ruby
curl -v\
  -H "X-Master-key: <YOUR_API_KEY>" \
  --request GET \<BIN_ID>
let req = new XMLHttpRequest();

req.onreadystatechange = () => {
  if (req.readyState == XMLHttpRequest.DONE) {
};"GET", "<BIN_ID>", true);
req.setRequestHeader("X-Master-Key", "<YOUR_API_KEY>");
import requests
url = '<BIN_ID>'
headers = {
  'X-Master-Key': '<YOUR_API_KEY>'

req = requests.get(url, json=None, headers=headers)
require 'net/http'
require 'json'

uri = URI("<BIN_ID>")
res = Net::HTTP.start(, uri.port, use_ssl: true) do |http|
  req =
  req['X-Master-Key'] = '<YOUR_API_KEY>'


puts res.body

Request Response

Success Status Code: 200
  "metadata": {
    "id":"<Bin Id>",
    "createdAt":"<Date & Time>",
    "private": <true/false>,
    "name": "<Bin Name>"
Error Status Code: 400, 401, 403, 404
  "message": "<Error Message>"

For more information on the error codes & errors you might possibly encounter, refer to the below section.

Error Reference

  • 400 Bad Request
  • 401 Unauthorized
  • 403 Forbidden
  • 404 Not Found
You need to pass Content-Type set to application/json

You need to pass Content-Type header set to application/json else the READ request for the XL Bin will fail.

Invalid XL Bin Id provided

You'll encounter this error if the Bin Id you are trying to access is invalid. Hence, ensure that the Bin Id you are passing is valid.

You need to pass X-Master-Key in the header to read a private XL bin

You'll encounter this error if you are not passing the X-Master-Key header which is required to authenticate your request while reading bins. In-order to fix this, pass the X-Master-Key header with a value of the API Key which you can find on the API Keys page.

X-Master-Key is invalid or the XL bin doesn't belong to your account

You could encounter this error if the X-Master-Key you've passed is invalid, or the XL Bin you are trying to access does exists but does not belong to your account.

Requests exhausted. Buy additional requests at

You'll encounter this error if you've consumed all the available requests. You can purchase additional requests.

XL bin not found or it doesn't belong to your account

You are trying to access an xl bin which does not exists or it does not belong to your account. Verify the Bin Id and try again.

Create a Free Account

Create an Account View Pricing