KrabyData

Documentation.

ETF holdings, fund facts and security identity from primary sources. Version 1.1.0 of the API, read-only, JSON over HTTPS. This page is built from the OpenAPI file, which you can also load into your own tools.

Base URL

https://api.krabydata.com/v1. Every answer is JSON: { "data": ... }, lists add "pagination", and an error is { "error": "code", "message": "..." }. Any website may call the API from a browser (CORS is open for GET), but your key is then visible to your visitors: call it from your server when you can.

Authentication

Send your key in a header on every request but /v1/health and /v1/stats:

Authorization: Bearer kd_...

A key is kd_ followed by 43 characters. It is shown once, when it is created; we keep only its hash and cannot show it again. A key is never read from the query string, so it does not end up in logs or browser history. A key is personal: one person or one product, not shared. Get a free key.

Limits and their headers

Each plan allows a number of requests per UTC day and per minute (see the plans). Every answer to a keyed request carries:

HeaderMeaning
X-RateLimit-LimitRequests your plan allows per UTC day.
X-RateLimit-RemainingRequests left today, this one counted.
Retry-AfterOn a 429 only: seconds to wait, until the next minute or until midnight UTC.

The day's count starts again at midnight UTC. Unlimited plans send no limit headers.

Errors

The status says what kind of problem it is, error says exactly which, and message says it in words. Codes do not change within v1.

StatuserrorWhen
400bad_requestThe resolver was given none of symbol, ticker with mic, or isin.
400bad_isinAn ISIN that is not two letters, nine characters and a check digit.
400bad_dateA date that is not YYYY-MM-DD.
400bad_sortA sort field the fund list does not know.
300ambiguousSeveral funds share that ticker. The answer lists them in candidates; ask again by ISIN.
401missing_keyNo Authorization header, or not in the form Bearer <key>.
401invalid_keyNot a KrabyData key, or a key that does not exist.
403revoked_keyThe key was revoked.
403unknown_planThe key's plan is no longer offered. Write to us.
404not_foundNo fund, security or route by that name.
404not_licensedA dataset your key may not see (see below).
404no_holdingsNo holdings stored for the fund on or before the date.
404suspect_holdingsThe only files for the date failed the weight check on write, and are held back. The message says why.
405method_not_allowedThe API is read-only: GET only.
429quota_exceededThe plan's requests for the UTC day are used up. Retry-After says when midnight UTC comes.
429rate_limitedToo many requests this minute. Retry-After says how many seconds to wait.
500internal_errorOur fault. Nothing to change on your side; tell us if it lasts.

What your key does not see, and why

KrabyData only passes on what its sources allow. PentaLab's own products see more than a customer's key; the difference is always the same, and it is stated here rather than discovered.

  • Funds from issuers that have not agreed. Daily holdings files of Global X (Europe and US) and VanEck Europe carry notices against reproduction and derivative works. Those funds answer 404 not_licensed and are left out of every list, until an issuer agrees in writing.
  • Their funds that file with the SEC. A Global X US fund also files Form N-PORT, which is public. Such a fund answers from its filings only: its ISIN, ticker, name, EDGAR ids, the fee in its SEC prospectus and its N-PORT dates. Its NAV, net assets, launch date and the issuer's daily files are not shown.
  • The resolver uses public evidence only. /v1/listings/resolve answers from OpenFIGI's listings, the security master rows SEC filings name with the ticker they give, and lines of SEC filings that carry their own ISIN. A symbol that only an issuer's file connects to an ISIN answers as an unknown symbol would, with no hint that anything was left out. The same rule applies to /v1/securities/{isin}.
  • No CUSIP and no SEDOL. CUSIP Global Services and LSEG own those codes and license them separately. Fields named cusip or sedol never appear in your answers.
  • FIGI with attribution. FIGIs are given, with "attribution": "FIGI data from OpenFIGI" in the answer, which you should keep beside them.

How old the data is

Holdings from SEC Form N-PORT are dated at the filing's report period end. Funds file every month, but only the third month of each quarter is made public, 60 days after the quarter ends, so the holdings are two to five months old. Every such answer carries source.freshness saying so, and asOf with the date. Identity answers are current.

Versions

The base path carries the major version. Within /v1, fields and routes may be added; nothing is removed, renamed or changes meaning without a /v2, which would run beside /v1 for a notice period. Read your JSON so that an unknown field is ignored. Questions: contact@krabydata.com.

Routes.

GET

/v1/health

no key needed

Service status, for status pages and uptime checks

Needs no key. Whether the database answers, each source's latest holdings date, and each collector's last run.

Answers

200Up
503The database does not answer

Fields of a 200 answer

  • okboolean
  • timestring (date-time)
  • databaseobject
    • okboolean
    • msinteger
  • holdingsarray of object
    • sourcestring
    • latestAsOfstring (date)
    • lastFetchedAtstring (date-time)
  • collectorsarray of object
    • collectorstring
    • startedAtstring (date-time)
    • finishedAtstring (date-time) or null
    • fundsinteger
    • filesinteger
    • rowsinteger
    • errorsinteger
  • lastRunobject or null The most recent of the collectors' runs
GET

/v1/stats

no key needed

What the service holds, for the site's front page

Needs no key. Funds, the holding lines of each fund's latest file, the securities in the master, and per source its funds and latest holdings date. Kept for a minute; the answer says when it was computed.

Answers

200The figures

Fields of a 200 answer

  • dataobject
    • fundsinteger
    • fundsWithHoldingsinteger
    • holdingLinesinteger Lines of each fund's latest holdings file
    • securitiesinteger ISINs in the security master
    • sourcesarray of object
      • sourcestring
      • namestring
      • externalDistributionboolean Whether external keys see this source
      • fundsinteger
      • fundsWithHoldingsinteger
      • fundsWithFeesinteger
      • holdingLinesinteger
      • latestAsOfstring (date) or null
  • asOfstring (date-time) When the figures were computed
GET

/v1/issuers

Sources collected, with their counts, latest date and last run

An external key sees only the issuers whose data may be redistributed.

Answers

200The issuers
401No key (missing_key) or an unknown one (invalid_key)
403A revoked key (revoked_key)
429Over the daily quota (quota_exceeded, until midnight UTC) or the per-minute rate (rate_limited)

Fields of a 200 answer

  • dataarray of object
    • idstring
    • namestring
    • websitestring or null
    • noticestring or null
    • externalDistributionboolean
    • fundsinteger
    • fundsWithHoldingsinteger
    • latestAsOfstring (date) or null
    • lastFetchedAtstring (date-time) or null
    • linesLatestinteger
    • lastRunobject or null
GET

/v1/etfs

A page of funds

Parameters

NameInTypeMeaning
issuerquerystringAn issuer id from /v1/issuers (sec-nport, globalx...)
qquerystringText found in the name, ticker or ISIN
sortquerystring: ticker name issuer isin fees launched nav holdingsAsOf lines
dirquerystring: asc descDefault asc
limitqueryintegerDefault 100
offsetqueryintegerDefault 0

Answers

200The page
400A malformed parameter (bad_date, bad_isin, bad_sort, bad_request)
401No key (missing_key) or an unknown one (invalid_key)
403A revoked key (revoked_key)
429Over the daily quota (quota_exceeded, until midnight UTC) or the per-minute rate (rate_limited)

Fields of a 200 answer

  • paginationobject
    • limitinteger
    • offsetinteger
    • countinteger
    • totalinteger
  • dataarray of object
    • isinstring
    • tickerstring or null
    • namestring
    • issuerstring
    • shareClassstring or null
    • themestring or null
    • sfdrstring or null
    • ongoingChargesPctnumber or null
    • inceptionDatestring (date) or null
    • countriesarray of string
    • netAssetsnumber or null
    • navnumber or null
    • navAsOfstring (date) or null
    • domicilestring or null
    • replicationstring or null
    • distributionFrequencystring or null
    • baseCurrencystring or null
    • indexNamestring or null
    • detailsAtstring (date-time) or null
    • holdingsobject or null
      • asOfstring (date)
      • countinteger
    • identifiedWeightPctnumber or null
    • edgarobject or null A US fund's ids in SEC EDGAR
      • cikstring
      • seriesIdstring or null
      • classIdstring or null
GET

/v1/etfs/{id}

One fund's facts

Parameters

NameInTypeMeaning
id requiredpathstringThe fund's ISIN, or its ticker when no other fund shares it (300 otherwise)

Answers

200The fund
300Several funds share that ticker; use the ISIN
401No key (missing_key) or an unknown one (invalid_key)
403A revoked key (revoked_key)
404No such fund or security (not_found), or a dataset an external key may not see (not_licensed)
429Over the daily quota (quota_exceeded, until midnight UTC) or the per-minute rate (rate_limited)

Fields of a 200 answer

  • dataobject
    • isinstring
    • tickerstring or null
    • namestring
    • issuerstring
    • shareClassstring or null
    • themestring or null
    • sfdrstring or null
    • ongoingChargesPctnumber or null
    • inceptionDatestring (date) or null
    • countriesarray of string
    • netAssetsnumber or null
    • navnumber or null
    • navAsOfstring (date) or null
    • domicilestring or null
    • replicationstring or null
    • distributionFrequencystring or null
    • baseCurrencystring or null
    • indexNamestring or null
    • detailsAtstring (date-time) or null
    • holdingsobject or null
      • asOfstring (date)
      • countinteger
    • identifiedWeightPctnumber or null
    • edgarobject or null A US fund's ids in SEC EDGAR
      • cikstring
      • seriesIdstring or null
      • classIdstring or null
    • issuerNamestring or null
    • historyobject
      • daysinteger Holdings dates stored
      • fromstring (date) or null
    • sourceobject Where the numbers came from, and how old they are
      • issuerstring or null
      • issuerNamestring or null
      • urlstring or null
      • fetchedAtstring (date-time) or null
      • sha256string or null
      • noticestring or null The source's own terms notice
      • externalDistributionboolean
      • freshnessstring or null How old this source's data is (N-PORT two to five months)
GET

/v1/etfs/{id}/holdings

A fund's holdings on a date

The latest file on or before date (today when omitted) whose weights passed the check on write. Lines keep the file's own identifiers; a line whose file gave no ISIN may carry one found by a rule, named in isinFrom.

Parameters

NameInTypeMeaning
id requiredpathstringThe fund's ISIN, or its ticker when no other fund shares it (300 otherwise)
datequerystring (date)

Answers

200The holdings
300Several funds share that ticker; use the ISIN
400A malformed parameter (bad_date, bad_isin, bad_sort, bad_request)
401No key (missing_key) or an unknown one (invalid_key)
403A revoked key (revoked_key)
404No such fund (not_found), not licensed for an external key (not_licensed), no file on or before the date (no_holdings), or only files held back by the weight check (suspect_holdings, with the reason)
429Over the daily quota (quota_exceeded, until midnight UTC) or the per-minute rate (rate_limited)

Fields of a 200 answer

  • dataobject
    • etfobject
      • isinstring
      • tickerstring or null
      • namestring
      • issuerstring
    • asOfstring (date)
    • requestedDatestring (date) or null
    • totalsobject
      • linesinteger
      • securitiesinteger
      • weightPctnumber
      • securitiesWeightPctnumber
      • cashWeightPctnumber
      • cryptoWeightPctnumber
      • otherWeightPctnumber
      • identifiedWeightPctnumber or null Share of the security weight whose lines carry an ISIN
    • sourceobject Where the numbers came from, and how old they are
      • issuerstring or null
      • issuerNamestring or null
      • urlstring or null
      • fetchedAtstring (date-time) or null
      • sha256string or null
      • noticestring or null The source's own terms notice
      • externalDistributionboolean
      • freshnessstring or null How old this source's data is (N-PORT two to five months)
    • attributionstring "FIGI data from OpenFIGI" when a line carries a FIGI (external keys)
    • holdingsarray of object
      • lineinteger
      • kindstring one of security, cash, crypto, other
      • namestring
      • isinstring or null
      • isinFromstring or null The file, or the rule that found the ISIN. one of file, cusip, master-cusip, master-sedol, treasury, master-ticker, successor
      • sedolstring or null Internal keys only
      • tickerstring or null
      • tickerFromstring or null one of file, master
      • countrystring or null
      • figistring or null
      • cusipstring or null Internal keys only
      • currencystring or null
      • sectorstring or null
      • assetCatstring or null N-PORT asset category (EC, EP, DBT...)
      • weightPctnumber or null
      • sharesnumber or null
      • pricenumber or null
      • marketValuenumber or null
GET

/v1/etfs/{id}/holdings/dates

Every holdings date stored for a fund

Parameters

NameInTypeMeaning
id requiredpathstringThe fund's ISIN, or its ticker when no other fund shares it (300 otherwise)

Answers

200The dates, newest first; a held-back date is listed with its reason and never served
300Several funds share that ticker; use the ISIN
401No key (missing_key) or an unknown one (invalid_key)
403A revoked key (revoked_key)
404No such fund or security (not_found), or a dataset an external key may not see (not_licensed)
429Over the daily quota (quota_exceeded, until midnight UTC) or the per-minute rate (rate_limited)

Fields of a 200 answer

  • dataobject
    • etfobject
      • isinstring
      • tickerstring or null
      • namestring
      • issuerstring
    • datesarray of object
      • asOfstring (date)
      • countinteger
      • fetchedAtstring (date-time)
      • suspectboolean
      • suspectReasonstring or null
GET

/v1/etfs/{id}/holdings/open

Security lines of the latest file still without an ISIN, heaviest first, and why

Parameters

NameInTypeMeaning
id requiredpathstringThe fund's ISIN, or its ticker when no other fund shares it (300 otherwise)

Answers

200The open lines
300Several funds share that ticker; use the ISIN
401No key (missing_key) or an unknown one (invalid_key)
403A revoked key (revoked_key)
404No such fund or security (not_found), or a dataset an external key may not see (not_licensed)
429Over the daily quota (quota_exceeded, until midnight UTC) or the per-minute rate (rate_limited)

Fields of a 200 answer

  • dataobject
    • etfobject
      • isinstring
      • tickerstring or null
      • namestring
      • issuerstring
    • asOfstring (date)
    • identifiedWeightPctnumber or null
    • openLinesinteger
    • openWeightPctnumber
    • openarray of object
      • lineinteger
      • namestring
      • tickerstring or null
      • cusipstring or null Internal keys only
      • assetCatstring or null
      • weightPctnumber or null
      • whystring one of tie: preferred, tie: share classes, successor unconfirmed, venue unknown, no candidate, debt, no identifier, resolvable
      • candidatesarray of string
GET

/v1/etfs/{id}/listings

Every venue a fund trades on, from OpenFIGI

Parameters

NameInTypeMeaning
id requiredpathstringThe fund's ISIN, or its ticker when no other fund shares it (300 otherwise)

Answers

200The listings
300Several funds share that ticker; use the ISIN
401No key (missing_key) or an unknown one (invalid_key)
403A revoked key (revoked_key)
404No such fund or security (not_found), or a dataset an external key may not see (not_licensed)
429Over the daily quota (quota_exceeded, until midnight UTC) or the per-minute rate (rate_limited)

Fields of a 200 answer

  • dataobject
    • etfobject
      • isinstring
      • tickerstring or null
      • namestring
      • issuerstring
    • listingsarray of object
      • figistring
      • isinstring
      • tickerstring
      • exchCodestring or null Bloomberg venue code
      • micstring or null
      • symbolstring or null Yahoo-style symbol where one exists
      • namestring or null
      • securityTypestring or null
      • fetchedAtstring (date-time)
    • attributionstring always FIGI data from OpenFIGI
GET

/v1/listings/resolve

The ISIN behind a symbol, a ticker on a venue, or the listings of an ISIN

Give one of symbol (a Yahoo-style symbol: DFNS.MI, NESN.SW, AMZN, BRK-B), ticker with mic, or isin. A fund is found in its OpenFIGI listings, a share in the security master, then in holdings lines. When several ISINs answer, isin is null and candidates lists them: the API never guesses. An external key's answer rests on public evidence only: OpenFIGI listings, the master rows SEC N-PORT filings name with the ticker they give, and N-PORT lines that carry their own ISIN.

Parameters

NameInTypeMeaning
symbolquerystring
tickerquerystring
micquerystringISO 10383 market identifier code
isinquerystring

Answers

200The answer, possibly empty
400A malformed parameter (bad_date, bad_isin, bad_sort, bad_request)
401No key (missing_key) or an unknown one (invalid_key)
403A revoked key (revoked_key)
429Over the daily quota (quota_exceeded, until midnight UTC) or the per-minute rate (rate_limited)

Fields of a 200 answer

  • dataobject
    • isinstring or null
    • candidatesarray of string
    • fundsarray of object
      • isinstring
      • tickerstring or null
      • namestring
      • issuerstring
    • listingsarray of object
      • figistring
      • isinstring
      • tickerstring
      • exchCodestring or null Bloomberg venue code
      • micstring or null
      • symbolstring or null Yahoo-style symbol where one exists
      • namestring or null
      • securityTypestring or null
      • fetchedAtstring (date-time)
    • securitiesarray of object
      • isinstring
      • namestring or null
      • currencystring or null
      • tickersarray of string
      • heldByFundsinteger
      • lastSeenstring (date) or null
      • cusipstring or null Internal keys only
      • countrystring or null
    • attributionstring always FIGI data from OpenFIGI
GET

/v1/securities/{isin}

One security from the master, with its succession

Parameters

NameInTypeMeaning
isin requiredpathstring

Answers

200The security
400A malformed parameter (bad_date, bad_isin, bad_sort, bad_request)
401No key (missing_key) or an unknown one (invalid_key)
403A revoked key (revoked_key)
404No such fund or security (not_found), or a dataset an external key may not see (not_licensed)
429Over the daily quota (quota_exceeded, until midnight UTC) or the per-minute rate (rate_limited)

Fields of a 200 answer

  • dataobject
    • isinstring
    • tickerstring or null
    • namestring or null
    • cusipstring or null Internal keys only
    • leistring or null
    • countrystring or null
    • firstSeenstring (date) or null
    • lastSeenstring (date) or null
    • heldByFundsinteger or null
    • succeededByobject or null
      • isinstring
      • effectiveFromstring (date) or null
      • evidenceobject
    • succeedsarray of object
      • isinstring
      • effectiveFromstring (date) or null
      • evidenceobject
GET

/v1/securities/{isin}/funds

The funds holding a security, from each fund's latest file on or before the date

Parameters

NameInTypeMeaning
isin requiredpathstring
datequerystring (date)

Answers

200The funds, heaviest weight first
400A malformed parameter (bad_date, bad_isin, bad_sort, bad_request)
401No key (missing_key) or an unknown one (invalid_key)
403A revoked key (revoked_key)
429Over the daily quota (quota_exceeded, until midnight UTC) or the per-minute rate (rate_limited)

Fields of a 200 answer

  • dataobject
    • isinstring
    • namestring or null
    • requestedDatestring (date) or null
    • fundsarray of object
      • isinstring
      • tickerstring or null
      • namestring
      • issuerstring
      • asOfstring (date)
      • weightPctnumber or null
      • sharesnumber or null
      • marketValuenumber or null