---
title: "Get dilution instrument rows by family"
method: GET
path: "/dilution/{ticker}/instruments"
tags: ["Dilution"]
---

# Get dilution instrument rows by family

`GET /dilution/{ticker}/instruments`

## Request

- Base URL: `https://api.signal8.ai/api/v1/public`
- URL: `https://api.signal8.ai/api/v1/public/dilution/{ticker}/instruments`
- Auth: API key in header `X-Api-Key`

The per-row instrument detail behind the snapshot summary, one
instrument family per request.

🔴 DO NOT SUM ACROSS FAMILIES. Families overlap by construction: a
resale registration (`shelfs`) can register shares that a `warrants` or
`convertibles` row already counts, or shares that are already
outstanding. The only additive totals are the ones
`/dilution/{ticker}/snapshot` publishes in `summary`.

🔴 A row may be WITHHELD by the correctness harness. Such a row is
returned with its numeric fields nulled and a withholding marker — it is
NOT absent, so a consumer can see that the family total is a lower
bound rather than silently reading a smaller book.

**Credit cost: 10**

## Path parameters

- `ticker` string, required

## Query parameters

- `family` string, required

## Response `200`

Instrument rows for the requested family

- object

## Other responses

- `400`: Invalid request parameters
- `401`: Missing or invalid API key
- `402`: Not enough credits for this request
- `403`: The API key's owner does not hold the per-user add-on this endpoint is sold under. 🔴 This is NOT a tier problem — a Pro subscription does not confer an add-on. Route the user to add-on purchase (`addonType` names which one), not to a plan upgrade. The distinct `ADDON_REQUIRED` code exists so the two flows can be told apart; treating it as `TIER_INSUFFICIENT` sends a paying customer to a page that cannot sell them what they were denied.
- `404`: Resource not found
- `429`: Rate limit exceeded

---

[API](https://skmtc.dev/signal8/apis/signal8-public-api.md) · [All operations](https://skmtc.dev/signal8/apis/signal8-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/signal8/apis/signal8-public-api/revisions/5a18ae8d6d58?raw)