# Read the facts of one or more listed instruments

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/registry/instruments` Callable today

The key presents the `availability.read` scope.

## The parameters

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

## What it answers

The instruments the ask named, each once in the order it named them: each row names the instrument by its CAIP-19 id, its chain, its wrapper programme and the token issuer's name, which stands null where the programme names none, and carries the programme's own facts - its legal form, whether the issuing company sponsors it, its transfer model, whether holding it needs the programme's own KYC - and the token it converts into, named by its CAIP-19 id and programme. An instrument the ask names that the registry does not list today answers nothing: an unknown, paused, unmapped, other-mode or other-tenant id carries no row. The next page's cursor is null: the ask is answered whole, one call.

- `items` Required. A list of objects with the fields below. It carries at most 200 items. `Each item` Required. An object with the fields below. `instrumentId` Required. A string. `chain` Required. A string. `wrapperName` Required. A string. It carries at least 1 and at most 128 characters. `tokenIssuerName` Required. A string. It carries at least 1 and at most 256 characters. It may also be null. `legalForm` Required. A string that is one of the values below. It may also be null. `synthetic_tracker` `security_entitlement_ucc8` `native_registered_share` `other` `issuerSponsored` Required. True or false. `transferModel` Required. A string that is one of the values below. It may also be null. `open` `permissioned_whitelist` `kycByWrapper` Required. True or false. `convertsTo` Required. An object with the fields below. It may also be null. `instrumentId` Required. A string. `wrapperName` Required. A string. It carries at least 1 and at most 128 characters.
- `nextCursor` Required. A string. It may also be null.

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