Read Bins API

The bins you store on, either Uncategorized or in a Collection can be Read using the Read Bins API.

The API allows you to Read Public & Private Bins. Moreover, using this API, you could also Read Versions of a specific Bin.



Read a specific Bin
Read a specific Bin Version
Disable Meta Data using Query Parameter instead of X-Bin-Meta header

Info You can use meta query parameter with any of the READ API path if you wish to disable the metadata of the header.

Read Latest Version of the Bin (without the need of specifying the exact version)

Info Using /latest will always return the latest version of the bin.

Request Type


Request Headers

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

Request Header Value Required
X-Master-Key <API_KEY> Yes
X-Access-Key <ACCESS_KEY> Yes
X-Bin-Meta <true / false> No
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-Access-Key Required

You can now access your private records with X-Access-Key header too. Refer to the FAQs for more information on X-Access-Key. Make sure you've granted Bins Read Access Permission to the Access Key you'll be using. You can create Access Keys on 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.

X-JSON-Path Optional

Using X-JSON-Path, you could access specific data from the bin instead of the entire bin. To access a particular data, you could use JSON accessors, like, for eg, users[0].firstName.

For in-depth documentation on suported JSONPath rules, refer to the JSON Path Documentation.

Request Query Parameters

Query Parameter Value Required
meta <true/false> No
meta Optional

If your application or a tool doesn't allow you to set the header in the request, you can control the metadata using the meta query parameter.

You can disable bin meta by setting the query param to false.

Code Samples

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

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

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

uri = URI("<BIN_ID>/<BIN_VERSION | latest>")
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
With Meta Data
  "record": {
    "sample": "Hello World"
  "metadata": {
    "id": "<BIN_ID>",
    "private": true
Without Meta Data (using X-Bin-Meta: false header) or meta=false query parameter
  "sample": "Hello World"

Important If you've passed X-JSON-Path header, it will always return an array of elements under "records" key if the provided JSON Path expression matches any element(s) in the bin, or an empty array if none were matched.

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
Invalid 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.

Bin version is invalid

Bin version you are trying to access is not valid.

Invalid X-JSON-Path expression passed

You'll encounter this error if you've have passed incorrect JSON Path expression.

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

You'll encounter this error if you are not passing the X-Master-Key or X-Access-Key header which is required to authenticate your request while reading bins. In-order to fix this, pass the X-Master-Key or X-Access-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 bin doesn't belong to your account

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

X-Access-Key passed does not have permission to read the bin.

Make sure you have granted Bins Read permission to the Access Key before using it to read the private bins.

Bin not associated to any user account

You are trying to access a bin which does not belong to any user.

Bins not associated to any user are now blocked. Contact the admin at for further info

Generally, you will never encounter this error. This error will be thrown if you are trying to access a Bin which was created without a user. These are the records which were created earlier where Authentication was not required to Create bins and hence, we have blocked these bins for countering spammy requests.

Requests exhausted. Buy additional requests at

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

Bin not found or it doesn't belong to your account

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

Bin version not found

You are trying to access a Version of a Bin which does not exist. Verify and pass a valid version else use /latest route instead.

Create a Free Account

Create an Account View Pricing