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

# bigdata_bonds_tearsheet

> Returns a company's bonds, or any corporate, sovereign or municipal bond by ISIN, with terms and latest prices.

## Overview

Get Bonds by Company or ISIN returns bond terms and the latest market data in one markdown table. Ask for a company's bonds with its `rp_entity_id`, or for specific bonds of any type (corporate, sovereign or municipal) by ISIN.

Each bond comes with its coupon, maturity date, currency, amount outstanding, seniority and status, and, unless you turn prices off, its latest price, yield and spread over the government benchmark.

## When to Use

* **Debt and maturity profile:** when does a company's debt mature, and how much is outstanding in each currency ("when does Ford's debt mature?")
* **Bond pricing:** what a company's bonds are trading at and yielding ("what are Apple's bonds yielding?")
* **ISIN lookup:** terms and latest price of specific bonds, including sovereign and municipal bonds
* **Credit context:** combine with `bigdata_company_tearsheet` for a fuller picture of a company's finances and debt

## How It Works

There are two ways to ask. Use one or the other, never both:

1. **By company (`rp_entity_id`):** get the company's ID from `find_securities`, then call `bigdata_bonds_tearsheet` with it. The tool returns all the bonds of the company's mapped issuers, active ones by default, up to 50 per page.
2. **By ISIN (`isins`):** call `bigdata_bonds_tearsheet` with up to 50 ISINs. The tool returns exactly those bonds, whatever their type or status. An ISIN with no bond comes back in `unknown_isins`.

Sovereign and municipal bonds are reached by ISIN. Asking by company returns a company's bonds only.

## Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `rp_entity_id` | string | One of the two | RavenPack entity ID of the issuing company, exactly 6 characters (e.g. `"D8442A"`). Obtain it from `find_securities`. |
| `isins` | array of strings | One of the two | 1 to 50 ISINs of corporate, sovereign or municipal bonds (e.g. `["US037833CH12"]`). Upper or lower case, spaces around them are ignored. |
| `status` | enum or null | No | With `rp_entity_id` only. `"active"` (default) for bonds outstanding and not yet matured, `"inactive"` for bonds matured or redeemed, `"defaulted"` for bonds in default, or `null` for every status. |
| `cursor` | string | No | With `rp_entity_id` only. The `pagination.cursor` of the previous call, to get the next page. |
| `limit` | integer | No | Most bonds per page, 1 to 50. Default `50`. |
| `include_prices` | boolean | No | Default `true`. Set to `false` when only the terms are needed: the Price, Yield and Spread columns are left out. |

### Important Notes

* Give `rp_entity_id` or `isins`, not both. A call with neither, or with both, is refused with a message saying what to change.
* `cursor` and `status` apply to a company request only. Looking up ISINs returns every bond asked for, whatever its status.
* A malformed ISIN is refused before any lookup, with a message naming it.

## Data Returned

The response is a markdown table, one row per bond, under a heading that names the company for a company request:

| Column | Description |
| - | - |
| **ISIN** | International Securities Identification Number of the bond |
| **Issuer** | Name of the issuing entity |
| **Coupon** | Annual coupon rate, in percent |
| **Maturity** | Maturity date. Empty for a bond with no maturity date, such as a perpetual bond |
| **Currency** | Currency of the bond |
| **Outstanding (mm)** | Amount outstanding, in millions of the bond's currency |
| **Rank** | Seniority, such as `senior` or `junior-subordinated` |
| **Status** | `active`, `inactive` or `defaulted` |
| **Price** | Latest price, as a percentage of par |
| **Yield** | Latest yield, in percent |
| **Spread (bp)** | Spread over the government benchmark, in basis points |

A cell with no data shows `–`. The same bonds are also returned as structured data, with further terms per bond: description, issue date, issue amount, interest payment frequency, and secured, guaranteed and callable status.

### Pagination

A company with more bonds than `limit` is answered page by page. When `pagination.has_cursor` is `true`, more bonds match: call again with the same `rp_entity_id` and `status`, and `cursor` set to `pagination.cursor`. The markdown also says so at the end of the table.

## Examples

### A company's bonds

`bigdata_bonds_tearsheet` with `{"rp_entity_id": "D8442A", "limit": 50}` (Apple Inc), first rows of the first page:

```markdown theme={null}
# Bonds

Active bonds of Apple Inc (D8442A).

| ISIN | Issuer | Coupon | Maturity | Currency | Outstanding (mm) | Rank | Status | Price | Yield | Spread (bp) |
|----|------|------|--------|--------|----------------|----|------|-----|-----|-----------|
| US037833CJ77 | Apple Inc | 3.35% | 2027-02-09 | USD | 2,250 | senior | active | 99.641 | 4.8074% | 50.34 |
| US037833CR93 | Apple Inc | 3.2% | 2027-05-11 | USD | 2,000 | senior | active | 99.398 | 4.4239% | 28.82 |
| US037833CX61 | Apple Inc | 3% | 2027-06-20 | USD | 1,000 | senior | active | 98.986 | 4.6976% | 34.1 |
| XS1292389415 | Apple Inc | 2% | 2027-09-17 | EUR | 1,000 | senior | active | 98.957 | 3.264% | 40.52 |
| US037833FD70 | Apple Inc | 4.65% | 2028-11-09 | USD | 1,000 | senior | active | – | – | – |
...

More bonds exist. Call again with the same arguments and cursor "eyJlZGkiOm51bGwsInNraXAiOjU2fQ".
```

### Sovereign bonds by ISIN

`bigdata_bonds_tearsheet` with `{"isins": ["US912810RH32", "DE0001102580", "GB00BMGR2809"]}`:

```markdown theme={null}
# Bonds

| ISIN | Issuer | Coupon | Maturity | Currency | Outstanding (mm) | Rank | Status | Price | Yield | Spread (bp) |
|----|------|------|--------|--------|----------------|----|------|-----|-----|-----------|
| US912810RH32 | United States Of America | 3.125% | 2044-08-15 | USD | 42,000.0635 | senior | active | 74.141 | 5.4079% | – |
| DE0001102580 | Germany | – | 2032-02-15 | EUR | 31,000 | senior | active | 85.032 | 3.1303% | – |
| GB00BMGR2809 | United Kingdom | 0.25% | 2031-07-31 | GBP | 43,587.911 | – | active | 81.149 | 4.7532% | – |
```

### A municipal bond by ISIN

`bigdata_bonds_tearsheet` with `{"isins": ["US64972JS667"]}`:

```markdown theme={null}
# Bonds

| ISIN | Issuer | Coupon | Maturity | Currency | Outstanding (mm) | Rank | Status | Price | Yield | Spread (bp) |
|----|------|------|--------|--------|----------------|----|------|-----|-----|-----------|
| US64972JS667 | New York City Transitional Finance Authority | 5.5% | 2052-11-01 | USD | 229.03 | – | active | – | – | – |
```

## Practical Tips

### Reading a Full Maturity Profile

Each page lists active bonds first, then by maturity date, earliest first, with bonds that have no maturity date last. The order holds within a page only, so a later page can start again from earlier maturities. For a company's full maturity profile, read every page before summarizing.

### Missing Prices

Not every bond has a recent price. When Price, Yield and Spread are `–`, the data has no price for that bond: report it as unpriced rather than estimating one. Municipal bonds and recently issued bonds are the most likely to come back unpriced.

### When a Spread Is Given

A spread is given only where the bond names a government benchmark: US, German, UK and Canadian government bonds, for bonds issued from 2015 on. Sovereign bonds have no spread, as they are the benchmark.

### Coverage by Company

A company request returns the bonds of the issuers mapped to that company. A company that issues debt through entities not mapped to it can show fewer bonds than it has outstanding. Look those bonds up by ISIN.

### Combining Currencies

The table reports each bond in its own currency. To total a company's debt, convert each currency before adding the amounts outstanding.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.