> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pagos.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# BIN Benchmark API Overview

> Query benchmarked metrics for a BIN, calculated from Pagos network transaction data

The Pagos BIN Benchmark API returns benchmark metrics for a given BIN range, calculated from the billions of transaction data points Pagos has ingested from merchants who opt in to data sharing. You can use this API to see how your own performance for a BIN compares to the broader Pagos network.

<Note>
  The BIN Benchmark API is only available to businesses that have opted in to data sharing with Pagos. Contact your Pagos Account Manager to enable this feature.
</Note>

## Authentication

The Pagos platform uses API keys to authenticate requests to all our services. See our [API Authentication](/authentication/authentication-overview) guide for full instructions on generating API keys and authenticating with the Pagos APIs.

## Look Up BIN Benchmark Data

You can use cURL on the command line to submit BIN Benchmark API requests, but you can also use API query tools like Postman or integrate the API directly into your systems. Here's a cURL example for benchmark details on BIN `41234567`:

```bash theme={null}
curl --request GET \
  --url 'https://bin.pagos.ai/bins/benchmark?bin=41234567' \
  --header 'Authorization: Bearer <api_key>'
```

This will return the available benchmark metrics for the BIN:

```json theme={null}
{
  "bin_benchmark": {
    "bin_matched": 412345,
    "auth_rate": {
      "cardholder_initiated": 0.865,
      "merchant_initiated": 0.838
    }
  }
}
```

Note that `bin_matched` (`412345`) has fewer digits than the `bin` value submitted (`41234567`). See [Partial Matches](#partial-matches) below for why.

<Note>
  If you have questions about the data returned for any given BIN, check out our [BIN Data FAQ pages](/bin-database/general-faq).
</Note>

For a full list of response fields, see the [BIN Benchmark API Dictionary](/bin-data-APIs/bin-benchmark-api-dictionary).

## Partial Matches

If you submit a BIN longer than six digits, Pagos may not have enough transaction volume at that full length to calculate a reliable benchmark. In that case, we fall back to the closest shorter BIN-6 prefix that has sufficient data. `bin_matched` relays that shorter prefix rather than the full value you submitted.

Use `bin_matched` to tell whether a response reflects your exact BIN or a broader fallback match. In the example above, querying the 8-digit BIN `41234567` returned benchmark data for the 6-digit prefix `412345`.

## Missing or Insufficient Data

The `bin_benchmark` object is returned as `null` when Pagos can't provide a benchmark for the queried BIN, which happens in two cases:

* **Missing BIN** - The BIN doesn't exist in the Pagos BIN Database
* **Insufficient data** - The BIN exists, but Pagos doesn't have enough transaction volume for it to calculate a reliable benchmark

In both cases, the API will not charge you for a failed benchmark lookup:

```json theme={null}
{
  "bin_benchmark": null
}
```

## BIN Benchmark API Limits

The following are the API limits for BIN Benchmark API calls:

| BIN Benchmark API    | API Endpoint      | API Limit                  |
| :------------------- | :---------------- | :------------------------- |
| BIN Benchmark Lookup | `/bins/benchmark` | 100 calls every 10 seconds |

## BIN Benchmark API IP Addresses

The following static IP addresses can be used to allowlist API traffic to the Pagos BIN Benchmark API:

* `13.248.157.210`
* `166.117.218.160`

## Testing

You can explore the Pagos BIN Benchmark API in sandbox by enabling [Test Mode](/getting-started/managing-your-pagos-account#test-mode) and following the [testing](/bin-data-APIs/bin-benchmark-api-testing) details.