Family catalog

GET/api/v1/families/{family}/catalog

Symbols in one family, with names and date spans. History floors trim dateMin.

Description

Returns the catalog for one family. dateMin on each row is raised to the caller’s history floor. There is no teaser on this API — Free receives 403 except listed US stocks and listed fundamentals; Basic also includes delisted US stocks; Pro also includes index membership. There is no query string.

Authentication

v1 is client_id plus client_secret on every protected GET. A browser session is not enough. Google sign-in is for the website only — do not send a session cookie to v1.

HTTP Basic — Authorization: Basic base64(client_id:client_secret)
Headers — X-Client-Id and X-Client-Secret

Create or rotate credentials on Account. Full notes are on Authentication.

Path parameters

Parameter	In	Type	Required	Description
`family`	path	string	Yes	Family slug from GET /api/v1/families (for example us-equities).

Query parameters

These GETs take no query string except listed fundamentals, sector and index fundamentals, the stock universe, corporate events, dividend and split history, and valuation, which use symbols (the stock universe catalog also takes kind, sector, industry, and format; corporate events also take from and to; dividend and split history also takes types, from, and to), and FX rates, which use currencies with date or from and to. Path parameters select the family and symbol. The plan window is applied on the server.

Example request

curl -sS -u "$CLIENT_ID:$CLIENT_SECRET" \
  https://barquant.dev/api/v1/families/us-equities/catalog

Response attributes

Field	Type	Description
`family`	object	The same summary object as the list endpoint, for this slug.
`symbols`	object[]	Every symbol in the catalog, with dateMin raised to the plan floor.
`symbols[].symbol`	string	Ticker as published.
`symbols[].safeSymbol`	string	File-safe form of the ticker.
`symbols[].name`	string \| null	Security name when the catalog has it; otherwise null.
`symbols[].rows`	number	Published session count before the plan window trim.
`symbols[].dateMin`	string \| null	First session in this plan’s history window.
`symbols[].dateMax`	string \| null	Last session in the catalog.

Sample response

{
  "family": {
    "slug": "us-equities",
    "label": "US stocks",
    "kind": "prices",
    "status": "ready",
    "allowed": true,
    "requiredPlan": null,
    "historyYears": 10,
    "dateMin": "2016-09-13",
    "dateMax": "2026-09-11"
  },
  "symbols": [
    {
      "symbol": "IBM",
      "safeSymbol": "IBM",
      "name": "International Business Machines",
      "rows": 3200,
      "dateMin": "2016-09-13",
      "dateMax": "2026-09-11"
    }
  ]
}

Errors

Status	When
401	Missing or wrong client_id / client_secret.
403	Authenticated, but this plan does not include that family. v1 does not return a teaser catalog.
404	The family path is not a known slug.
429	Daily quota or per-minute plan quota. Read Retry-After and X-RateLimit-* headers.

401 body:

{
  "error": "Unauthorized"
}

403 body:

{
  "error": "This plan does not include that family.",
  "plan": "free",
  "requiredPlan": "unlimited"
}

429 body (per-minute / daily):

{
  "error": "Too many requests."
}

Plan access

Free: listed US stocks and listed fundamentals. Basic: listed US stocks, listed fundamentals, and delisted US stocks. Pro and Unlimited: listed, delisted, listed fundamentals, and index membership. Denied families return 403. Unknown slugs return 404.

Daily and per-minute quotas live on Plans and limits.