# Read the benefits one or more instruments carry

One call of the distributor API, read from the interface description Yutai publishes. Every sample answer on this page is simulated: no real holder's data stands behind it. The formats every value travels in are the [identifiers page](/docs/identifiers)'s.

## The call

GET `/v1/availability` Callable today

The key presents the `availability.read` scope.

The get started page shows [how a platform gets a key](/docs/get-started#key-heading).

## The parameters

`instruments`: Required. The instruments to read: one or more, at most 200 in one read, each an ISIN such as US0000000009 or a CAIP-19 instrument id such as eip155:88880/erc20:0x0000000000000000000000000000000000000000. It sits in the query.

`country`: Required. The market whose stored policy shapes the answer: its two-letter country code, such as PT. It sits in the query.

## What it answers

The instruments the request named, each once in the order it named them, keyed by its security's ISIN: an instrument the registry does not resolve and a company with no benefit to offer are left out. Each row names the market display policy its shape stands under - full carries the benefits, badge_only the count alone - and the market the ask names shapes every row, full when that market stores no policy.

- `instruments` Required. A list of objects with the fields below. It carries at most 200 items. `Each item` Required. An object with the fields below. `isin` The instrument's ISIN, in the registry's canonical spelling. Required. A string. `display` full lists the benefits, badge_only carries the count alone. Required. A string that is one of the values below. `full` `badge_only` `count` How many benefits the company offers in the caller's country. Required. A whole number, from 1 to 500. `illustrative` True when every benefit the count counts is illustrative, meaning an example Yutai made up rather than a real offer. Required. True or false. `benefits` The benefits the count counts, present on a full row and absent on a badge_only row. Optional. A list of objects with the fields below. It carries at most 500 items. `Each item` Required. An object with the fields below. `name` The benefit's name as the company writes it. Required. A string. It carries at least 1 and at most 128 characters. `requirement` What the holder must do to reach the benefit, in the company's own short words. Required. A string. It carries at least 1 and at most 512 characters. `fulfilment` How the benefit reaches the holder: CODE for a discount code or voucher, POINTS_CREDIT for points, VENUE_REDEMPTION for access at the venue, CHAIN_MINT for a digital collectible and TOKEN_TRANSFER for a token sent to the holder's wallet. Required. A string that is one of the values below. `CODE` `POINTS_CREDIT` `VENUE_REDEMPTION` `CHAIN_MINT` `TOKEN_TRANSFER` `illustrative` True when the benefit is an example Yutai made up, not an offer a real company has agreed to. Required. True or false.

## The errors

Every refused call answers one object with one field, message: the plain sentence that says what did not happen. The sentence carries 1 to 512 characters, so a refusal never carries an id, a code or an exception's text.

| Status | What it answers |

| --- | --- |

| 400 | The query could not be read. |

| 401 | The key is missing, malformed, unknown, revoked or expired. |

| 403 | The key does not carry the scope. The call is also refused with 403, nothing read, when the distributor is paused, suspended or closed, when the key is paused, or when the key presents from an origin it does not allow. |

| 429 | The key made too many calls this minute. The Retry-After header names the seconds until the next window opens. Nothing was read. |

| 500 | The read failed inside Yutai. Nothing was changed. |

| 503 | The data source this read needs is not live yet, so the read is refused. Nothing was read. |

The errors and limits page carries [every refusal status the document declares](/docs/errors#statuses-heading), each in its own words, beside the calls that answer it.