API reference

One REST surface, 17 endpoints, one key. Every route is versioned under a single base URL, every collection paginates the same way, and every error is the same shape.

Base URL

https://api.hedg3.ai/v1

Pricing and plan limits are on the API overview. Keys are minted from your account settings once your subscription is active.

Authentication

Send your key as a bearer token. Keys are prefixed so a leaked one is identifiable on sight, stored only as a hash, and shown in plaintext once, at creation. There is no way to recover one afterwards. Mint a new key and revoke the old.

A query-string token is deliberately not supported: it ends up in browser history, proxy logs and referrer headers.

Header

Authorization: Bearer hg3_live_...

Revocation takes effect immediately because the authorizer caches nothing. Both market-data subscriber agreements are re-checked on every request, not only at mint, so a lapsed agreement stops the key rather than silently degrading it.

Response shape

Every data route returns rows under data and context under meta. The two introspection routes are the exception and return a bare object.

Envelope

{
  "data": [ /* rows */ ],
  "meta": {
    "dataset": "congress",
    "count": 50,
    "cursor": "eyJQSyI6…",
    "source": "…",
    "since": "2026-07-16",
    "reportingDelay": "…",
    "coverageNote": "…"
  }
}

meta.source names the originating public source for the rows on that page.
meta.reportingDelay appears on the datasets that have a statutory one. It is stated rather than netted out. Rows are as-reported and are never back-dated.
meta.coverageNote appears where coverage is genuinely partial. A known gap is on the response, not left to be inferred from missing rows.

Pagination

Cursor-based. Pass the previous response's meta.cursor back as cursor. Walk until it is null.

A null cursor means the walk PROVED there is nothing more, not that this page came back short. A filtered page can legitimately return fewer rows than your limit and still hand you a live cursor. That is the correct behaviour, not an empty result.

Walking a dataset

cursor=""
while true; do
  resp=$(curl -s -H "Authorization: Bearer hg3_live_..." \
    "https://api.hedg3.ai/v1/data/insiders?limit=500&cursor=$cursor")
  echo "$resp" | jq -c '.data[]'
  cursor=$(echo "$resp" | jq -r '.meta.cursor // empty')
  [ -z "$cursor" ] && break
done

Rate limits

Two independent limits: a per-minute burst that protects the platform, and a daily allowance that is what you are buying. The burst is the same on every tier.

Tier	Per minute	Per day	Lookback
Basic	120	20,000	30 days
Advanced	120	50,000	90 days
Custom	120	Negotiated	Negotiated

Headers

X-RateLimit-LimitYour per-minute burst allowance.

X-RateLimit-RemainingRequests left in the current minute.

X-RateLimit-ResetUnix epoch at which the minute window rolls.

X-RateLimit-Limit-DayYour daily allowance.

X-RateLimit-Remaining-DayRequests left today.

These ride successful responses only. A 401, a scope 403 or either 429 carries none of them, so pace from the last successful response rather than from the rejection. The minute window is fixed rather than sliding, so a burst spanning a boundary can briefly clear up to twice the limit.

/data/meta/usage reports your remaining daily allowance and is not itself charged against it.

Errors

RFC 7807 problem details, with a requestId on every one. Quote it to support and we can find the exact request.

Error

{
  "type": "https://hedg3.ai/errors/api-quota",
  "title": "Daily quota exceeded",
  "status": 429,
  "detail": "Daily limit of 50000 requests reached.",
  "requestId": "a1b2c3d4-…"
}

Types

api-unauthorized401The key is missing, unknown, revoked or expired.

api-scope403The key is valid but not scoped for this dataset.

api-quota429The daily allowance is spent.

api-rate-limit429The per-minute burst allowance is spent.

api-validation400A required parameter is missing, or a value is outside its allowed set.

api-not-found404The dataset is not currently served.

One exception worth knowing before you write the handler: the gateway answers an authorizer rejection itself, so the body is NOT problem-details. That covers an unknown key, an inactive subscription and an outstanding agreement. Branch on the status first and parse the body second.

Public record

GET/data/congress

Congressional trading disclosures

Reported trades disclosed by sitting members, newest first.

Requires the read:congress scope.

Coverage is House-only today. That gap is stated in meta.coverageNote on every response rather than left for you to infer from missing rows.
meta.reportingDelay carries the statutory delay. Rows are as-reported and are not back-dated.

Parameters

limitintegerdefault 100: Rows per page. Clamped to 1-500; a non-numeric value falls back to the default rather than erroring.
cursorstring: Opaque page cursor from the previous response's meta.cursor. A malformed cursor returns 400.
sincestring (YYYY-MM-DD)default your tier's lookback floor: Earliest date to return. CLAMPED, never rejected. Asking for more history than your tier allows returns the tier's floor instead of an error.
symbolstring: Filter to one ticker. Upper-cased server-side.
memberstring: Exact member name. Case-sensitive.

Response fields

disclosedAtstringWhen the disclosure published.

transactionDatestringWhen the trade was made.

reportedAtstringFiling timestamp as reported.

symbolstringTicker, where the disclosure names one.

memberstringDisclosing member.

chamberstringChamber, where reported.

actionstringPurchase / sale / exchange, as reported.

amountRangestringThe disclosed value BAND. Disclosures report a range, not an amount.

transactionCountnumberTransactions folded into the row.

sourcestringOriginating public source for this row.

Test it outRecorded · 2026-08-15

limitcursorsincesymbolmember

GET https://api.hedg3.ai/v1/data/congress?limit=3&symbol=VSNT&member=Kevin%20Hern

Response

200 · 1 row

{
  "data": [
    {
      "action": "SALE",
      "amountRange": "$1,001 - $15,000",
      "chamber": null,
      "disclosedAt": "2026-08-12",
      "member": "Kevin Hern",
      "reportedAt": "2026-08-12",
      "source": "house_clerk",
      "symbol": "VSNT",
      "transactionCount": 1,
      "transactionDate": "2026-08-05"
    }
  ],
  "meta": {
    "dataset": "congress",
    "cursor": null
  }
}

No request leaves your browser. These are real responses this endpoint has returned, recorded and filtered locally.

GET/data/insiders

Insider transactions

Open-market transactions by company insiders, newest first.

Requires the read:insiders scope.

Parameters

limitintegerdefault 100: Rows per page. Clamped to 1-500; a non-numeric value falls back to the default rather than erroring.
cursorstring: Opaque page cursor from the previous response's meta.cursor. A malformed cursor returns 400.
sincestring (YYYY-MM-DD)default your tier's lookback floor: Earliest date to return. CLAMPED, never rejected. Asking for more history than your tier allows returns the tier's floor instead of an error.
symbolstring: Filter to one ticker.

Response fields

datestringTransaction date as reported.

symbolstringTicker.

insiderstringReporting person.

titlestringTheir role at the issuer.

actionstringBuy / sell, as reported.

sharesnumberShare count.

pricePerSharenumberThe price REPORTED IN THE FILING. It is a public-record figure, not a market quote.

transactionCodestringThe filing's own transaction code.

cikstringIssuer identifier.

Test it outRecorded · 2026-08-15

limitcursorsincesymbol

GET https://api.hedg3.ai/v1/data/insiders?limit=3&symbol=ZETA

Response

200 · 1 row

{
  "data": [
    {
      "action": "Grant",
      "cik": "1865076",
      "date": "2026-08-14",
      "insider": "Ravella Satish",
      "pricePerShare": 0,
      "shares": 51696,
      "symbol": "ZETA",
      "title": "Chief Accounting Officer",
      "transactionCode": "G"
    }
  ],
  "meta": {
    "dataset": "insiders",
    "cursor": null
  }
}

No request leaves your browser. These are real responses this endpoint has returned, recorded and filtered locally.

GET/data/institutions

Institutional filers

Which filers this API serves, and their CIKs.

Requires the read:institutions scope.

A curated set of managers, not every 13F filer. This is the list the two routes below accept. A CIK that is not here has no data to return.
Served from the registry rather than the store, so it costs no read and always matches what the detail route will accept.

Response fields

cikstringZero-padded CIK. Use it on the filer routes below.

namestringManager name.

Test it outRecorded · 2026-08-15

No parameters.

GET https://api.hedg3.ai/v1/data/institutions

Response

200 · 3 rows

{
  "data": [
    {
      "cik": "0001067983",
      "name": "Berkshire"
    },
    {
      "cik": "0001649339",
      "name": "Scion"
    },
    {
      "cik": "0001336528",
      "name": "Pershing Square"
    }
  ],
  "meta": {
    "dataset": "institutions-index",
    "cursor": null
  }
}

No request leaves your browser. These are real responses this endpoint has returned, recorded and filtered locally.

GET/data/institutions/{cik}

Institutional filings

A manager's filed quarters, newest first.

Requires the read:institutions scope.

This route takes NO `since` and applies NO lookback clamp. A filing history is not a rolling window, so your tier's lookback does not truncate it.

Parameters

cikstringrequired: The manager's identifier.
limitintegerdefault 100: Rows per page, 1-500.
cursorstring: Page cursor.

Response fields

cikstringManager identifier.

managerstringManager name as filed.

quarterstringReporting quarter.

accessionstringFiling accession number.

positionCountnumberPositions in the filing.

Test it outRecorded · 2026-08-15

cikreqlimitcursor

GET https://api.hedg3.ai/v1/data/institutions/0001067983?limit=1

Response

200 · 1 row

{
  "data": [
    {
      "accession": "0001193125-26-226661",
      "cik": "0001067983",
      "manager": "Berkshire",
      "positionCount": 90,
      "quarter": "2026Q1"
    }
  ],
  "meta": {
    "dataset": "institutions",
    "cursor": null
  }
}

No request leaves your browser. These are real responses this endpoint has returned, recorded and filtered locally.

GET/data/institutions/{cik}/holdings

Institutional holdings

The positions inside a manager's filings.

Requires the read:institutions scope.

Holdings are filed by CUSIP, not by ticker. A row carries the identifier the filing carried, so mapping it to a symbol is the caller's step.

Parameters

cikstringrequired: The manager's identifier.
limitintegerdefault 100: Rows per page. Clamped to 1-500; a non-numeric value falls back to the default rather than erroring.
cursorstring: Opaque page cursor from the previous response's meta.cursor. A malformed cursor returns 400.
sincestring (YYYY-MM-DD)default your tier's lookback floor: Earliest date to return. CLAMPED, never rejected. Asking for more history than your tier allows returns the tier's floor instead of an error.
quarterstring: Exact quarter. Omit for the most recent filed.

Response fields

cusipstringSecurity identifier as filed.

issuerstringIssuer name as filed.

valueUsdnumberReported position value.

sharesnumberReported share count.

quarterstringReporting quarter.

Test it outRecorded · 2026-08-15

cikreqlimitcursorsincequarter

GET https://api.hedg3.ai/v1/data/institutions/0001067983/holdings?limit=3&quarter=2026Q1

Response

200 · 3 rows

{
  "data": [
    {
      "cusip": "H1467J104",
      "issuer": "CHUBB LTD SWITZ",
      "quarter": "2026Q1",
      "shares": 34249183,
      "valueUsd": 11162836215
    },
    {
      "cusip": "92343E102",
      "issuer": "VERISIGN INC",
      "quarter": "2026Q1",
      "shares": 8989880,
      "valueUsd": 2232726597
    },
    {
      "cusip": "829933100",
      "issuer": "SIRIUSXM HOLDINGS INC",
      "quarter": "2026Q1",
      "shares": 124807117,
      "valueUsd": 2880548260
    }
  ],
  "meta": {
    "dataset": "institution-holdings",
    "cursor": null
  }
}

No request leaves your browser. These are real responses this endpoint has returned, recorded and filtered locally.

GET/data/ipos

IPO registrations

Registration filings in the pre-listing pipeline, newest first.

Requires the read:ipos scope.

This is a REGISTRATION feed, not a pricing calendar. There is no offer date, price range or syndicate. A registrant that has not priced has none of those, and the API does not invent them.
`symbol` is legitimately empty for pre-listing registrants.

Parameters

limitintegerdefault 100: Rows per page. Clamped to 1-500; a non-numeric value falls back to the default rather than erroring.
cursorstring: Opaque page cursor from the previous response's meta.cursor. A malformed cursor returns 400.
sincestring (YYYY-MM-DD)default your tier's lookback floor: Earliest date to return. CLAMPED, never rejected. Asking for more history than your tier allows returns the tier's floor instead of an error.

Response fields

symbolstringTicker, once one is assigned.

companystringRegistrant name.

cikstringRegistrant identifier.

filedAtstringFiling date. The since parameter filters on this.

formTypestringRegistration form type.

filingUrlstringLink to the filing itself.

Test it outRecorded · 2026-08-15

limitcursorsince

GET https://api.hedg3.ai/v1/data/ipos?limit=3

Response

200 · 3 rows

{
  "data": [
    {
      "cik": "0001580149",
      "company": "BIOVIE INC.",
      "filedAt": "2026-08-14",
      "filingUrl": "https://www.sec.gov/Archives/edgar/data/1580149/000152013826000350/0001520138-26-000350-index.htm",
      "formType": "S-1/A",
      "symbol": "BIVI"
    },
    {
      "cik": "0001649739",
      "company": "BayFirst Financial Corp.",
      "filedAt": "2026-08-13",
      "filingUrl": "https://www.sec.gov/Archives/edgar/data/1649739/000164973926000056/0001649739-26-000056-index.htm",
      "formType": "S-1",
      "symbol": "BAFN"
    },
    {
      "cik": "0002094710",
      "company": "ARC Group Securities Acquisition II",
      "filedAt": "2026-08-13",
      "filingUrl": "https://www.sec.gov/Archives/edgar/data/2094710/000149315226037855/0001493152-26-037855-index.htm",
      "formType": "S-1/A",
      "symbol": null
    }
  ],
  "meta": {
    "dataset": "ipos",
    "cursor": null
  }
}

No request leaves your browser. These are real responses this endpoint has returned, recorded and filtered locally.

GET/data/shorts/{symbol}

Short data

Three distinct datasets behind one path: short interest, daily short volume, and fails to deliver.

Requires the read:shorts scope.

Short INTEREST and short VOLUME are different measurements and are routinely confused: interest is open positions at a settlement date, volume is one session's flow.
The fails dataset is published roughly a month in arrears. Its as-of date being weeks old is correct, not stale.
The fails file also carries a price column, which is deliberately not returned.

Parameters

symbolstringrequired: Ticker.
limitintegerdefault 100: Rows per page. Clamped to 1-500; a non-numeric value falls back to the default rather than erroring.
cursorstring: Opaque page cursor from the previous response's meta.cursor. A malformed cursor returns 400.
sincestring (YYYY-MM-DD)default your tier's lookback floor: Earliest date to return. CLAMPED, never rejected. Asking for more history than your tier allows returns the tier's floor instead of an error.
datasetinterest | volume | failsdefault interest: Which dataset to return. An unrecognised value returns 400, never a silent fallback to the default.

Response fields

symbolstringTicker. Present on all three datasets.

settlementDatestringinterest, fails: the settlement date the row reports.

sessionstringvolume: the trading session. NOTE the date field differs per dataset.

shortSharesnumberinterest: shares reported short.

priorShortSharesnumberinterest: the prior period's figure.

periodChangeSharesnumberinterest: change since the prior period.

periodChangePercentnumberinterest: that change as a percent.

daysToCovernumberinterest.

avgDailyVolumenumberinterest.

shortVolumenumbervolume: shares sold short in the session.

shortExemptVolumenumbervolume.

totalVolumenumbervolume: the reporting file's own total, which is NOT consolidated volume.

shortVolumeRationumbervolume: derived. Null when it cannot be computed, never 0.

marketsstringvolume: the venues folded in.

quantityFailednumberfails: the failed quantity.

cusipstringfails.

descriptionstringfails.

Test it outRecorded · 2026-08-15

symbolreqlimitcursorsincedataset

GET https://api.hedg3.ai/v1/data/shorts/AAPL?limit=3&dataset=volume

Response

200 · 3 rows

{
  "data": [
    {
      "markets": "B,Q,N",
      "session": "2026-08-14",
      "shortExemptVolume": 28481,
      "shortVolume": 3006663.211985,
      "shortVolumeRatio": 0.32931010024083074,
      "symbol": "AAPL",
      "totalVolume": 9130188.262632
    },
    {
      "markets": "B,Q,N",
      "session": "2026-08-13",
      "shortExemptVolume": 33782.75,
      "shortVolume": 4566073.74883,
      "shortVolumeRatio": 0.3594940037647683,
      "symbol": "AAPL",
      "totalVolume": 12701390.568444
    },
    {
      "markets": "B,Q,N",
      "session": "2026-08-12",
      "shortExemptVolume": 43970.5,
      "shortVolume": 5521379.994964,
      "shortVolumeRatio": 0.3867083540850395,
      "symbol": "AAPL",
      "totalVolume": 14277891.689275
    }
  ],
  "meta": {
    "dataset": "shorts",
    "cursor": null
  }
}

No request leaves your browser. These are real responses this endpoint has returned, recorded and filtered locally.

GET/data/lobbying

Lobbying disclosures

Filed lobbying activity, newest first.

Requires the read:lobbying scope.

Parameters

limitintegerdefault 100: Rows per page. Clamped to 1-500; a non-numeric value falls back to the default rather than erroring.
cursorstring: Opaque page cursor from the previous response's meta.cursor. A malformed cursor returns 400.
sincestring (YYYY-MM-DD)default your tier's lookback floor: Earliest date to return. CLAMPED, never rejected. Asking for more history than your tier allows returns the tier's floor instead of an error.
clientstring: Exact client name.

Response fields

datestringFiling date.

clientstringClient as filed.

firmstringRegistrant as filed.

issuestringIssue area as filed.

amountUsdnumberReported amount.

symbolstringTicker, where the client maps to one. Frequently absent.

Test it outRecorded · 2026-08-15

limitcursorsinceclient

GET https://api.hedg3.ai/v1/data/lobbying?limit=3&client=TITLE%20IV-A%20COALITION

Response

200 · 3 rows

{
  "data": [
    {
      "amountUsd": null,
      "client": "TITLE IV-A COALITION",
      "date": "2026-08-15",
      "firm": "ALLIED FOR PROGRESS",
      "issue": "Education",
      "symbol": null
    },
    {
      "amountUsd": null,
      "client": "NATIONAL SUMMER LEARNING ASSOCIATION",
      "date": "2026-08-15",
      "firm": "ALLIED FOR PROGRESS",
      "issue": "Education",
      "symbol": null
    },
    {
      "amountUsd": null,
      "client": "BUILD AMERICA'S SCHOOL INFRASTRUCTURE COALITION (BASIC)",
      "date": "2026-08-15",
      "firm": "ALLIED FOR PROGRESS",
      "issue": "Education",
      "symbol": null
    }
  ],
  "meta": {
    "dataset": "lobbying",
    "cursor": null
  }
}

No request leaves your browser. These are real responses this endpoint has returned, recorded and filtered locally.

GET/data/contracts

Federal contract awards

Awarded federal contracts, newest first.

Requires the read:contracts scope.

Parameters

limitintegerdefault 100: Rows per page. Clamped to 1-500; a non-numeric value falls back to the default rather than erroring.
cursorstring: Opaque page cursor from the previous response's meta.cursor. A malformed cursor returns 400.
sincestring (YYYY-MM-DD)default your tier's lookback floor: Earliest date to return. CLAMPED, never rejected. Asking for more history than your tier allows returns the tier's floor instead of an error.
agencystring: Exact awarding agency name.

Response fields

datestringAward date.

agencystringAwarding agency.

contractorstringAwardee.

awardIdstringAward identifier.

amountUsdnumberAward amount.

symbolstringTicker, where the contractor maps to one. Frequently absent.

Test it outRecorded · 2026-08-15

limitcursorsinceagency

GET https://api.hedg3.ai/v1/data/contracts?limit=3&agency=United%20States%20Chemical%20Safety%20Board

Response

200 · 3 rows

{
  "data": [
    {
      "agency": "United States Chemical Safety Board",
      "amountUsd": 18692.2,
      "awardId": "95315826F00009",
      "contractor": "INTEGRATION TECHNOLOGIES GROUP, INC.",
      "date": "2026-08-13",
      "symbol": null
    },
    {
      "agency": "United States Chemical Safety Board",
      "amountUsd": 291312,
      "awardId": "95315826F00007",
      "contractor": "ABBOTT MEDIA PRODUCTIONS LLC",
      "date": "2026-08-13",
      "symbol": null
    },
    {
      "agency": "U.S. Agency for Global Media",
      "amountUsd": 200000,
      "awardId": "95170026K0032",
      "contractor": "PAYDESK LIMITED",
      "date": "2026-08-13",
      "symbol": null
    }
  ],
  "meta": {
    "dataset": "contracts",
    "cursor": null
  }
}

No request leaves your browser. These are real responses this endpoint has returned, recorded and filtered locally.

GET/data/economy/calendar

Economic calendar

Scheduled economic releases.

Requires the read:economy scope.

This is the ONE route sorted ASCENDING, because it is a forward calendar and oldest-first is the useful order.
There is no forecast or consensus field. It is not published on this feed, so it is not invented.

Parameters

limitintegerdefault 100: Rows per page. Clamped to 1-500; a non-numeric value falls back to the default rather than erroring.
cursorstring: Opaque page cursor from the previous response's meta.cursor. A malformed cursor returns 400.
sincestring (YYYY-MM-DD)default your tier's lookback floor: Earliest date to return. CLAMPED, never rejected. Asking for more history than your tier allows returns the tier's floor instead of an error.

Response fields

namestringRelease name.

datestringScheduled date.

countrystringCountry code.

importancestringRelative importance as published.

actualnumberReported value, once released.

previousnumberThe prior period's value.

Test it outRecorded · 2026-08-15

limitcursorsince

GET https://api.hedg3.ai/v1/data/economy/calendar?limit=3

Response

200 · 3 rows

{
  "data": [
    {
      "actual": null,
      "country": "US",
      "date": "2026-12-31",
      "importance": 2,
      "name": "Initial Jobless Claims",
      "previous": 209000
    },
    {
      "actual": null,
      "country": "US",
      "date": "2026-12-24",
      "importance": 2,
      "name": "Initial Jobless Claims",
      "previous": 209000
    },
    {
      "actual": null,
      "country": "US",
      "date": "2026-12-23",
      "importance": 2,
      "name": "Housing Starts",
      "previous": 1427
    }
  ],
  "meta": {
    "dataset": "economy",
    "cursor": null
  }
}

No request leaves your browser. These are real responses this endpoint has returned, recorded and filtered locally.

GET/data/sic/{symbol}

SIC classification history

Point-in-time industry classification, as filed with the SEC.

Requires the read:sic scope.

SIC, not GICS, and not a current sector label. It is what the filer told the SEC at filing date, so it lags reality and changes rarely.
That lag is the point for a point-in-time backtest: it is the classification a contemporaneous reader would have had. Every observation carries its own asOfDate so it is never read as current.
Source is the SEC Financial Statement Data Sets, taken direct from the SEC.

Parameters

symbolstringrequired: Ticker. Upper-cased server-side.

Response fields

symbolstringTicker.

cikstringFiler CIK.

observationsarrayEach entry carries asOfDate and the SIC recorded then.

Test it outRecorded · 2026-08-15

symbolreq

GET https://api.hedg3.ai/v1/data/sic/AAPL

Response

200 · 1 row

{
  "data": [
    {
      "cik": "320193",
      "observations": [
        {
          "asOfDate": "2025-01-31",
          "sic": "3571"
        }
      ],
      "symbol": "AAPL"
    }
  ],
  "meta": {
    "dataset": "sic",
    "cursor": null
  }
}

No request leaves your browser. These are real responses this endpoint has returned, recorded and filtered locally.

hedg3 output

GET/data/desk

Desk picks

Published picks from the automated desks, with their settled outcomes.

Requires the read:desk scope.

Always returns meta.cursor: null, because your tier's lookback window IS the page.

Parameters

limitintegerdefault 100: Rows, 1-500.
sincestring (YYYY-MM-DD): Earliest publish date, clamped to your tier's lookback.
deskstring: Filter to one desk.

Response fields

pickIdstringStable identifier.

deskstringPublishing desk.

publishedAtstringPublish timestamp.

symbolstringUnderlying.

strategystringStructure name.

rightstringcall | put, for the representative leg.

strikenumberRepresentative leg strike.

expirystringRepresentative leg expiry.

legsarrayEach leg: side, right, strike, expiry, quantity. Structure only. Per-leg pricing, greeks and open interest are not served on any route.

modeledEntrynumberThe modelled entry the pick was published at.

stopLossPctnumberStop, as a fraction of entry.

profitTargetsarrayTarget levels as published.

modeledWinProbabilitynumberModelled probability of profit at publish.

dteAtPublishnumberDays to expiry at publish.

statusstringactive, or a terminal outcome.

outcomeobject | nullNull while active. Once settled: realizedPct, exitReason, resolvedAt. realizedPct is a FRACTION, so 1.0 means +100% and reading it as a percent under-reports by 100x.

Test it outRecorded · 2026-08-15

limitsincedesk

GET https://api.hedg3.ai/v1/data/desk?limit=3&desk=spread-shop

Response

200 · 3 rows

{
  "data": [
    {
      "desk": "spread-shop",
      "dteAtPublish": 15,
      "expiry": "2026-08-28",
      "legs": [
        {
          "expiry": "2026-08-28",
          "quantity": 1,
          "right": "put",
          "side": "buy",
          "strike": 34.5
        },
        {
          "expiry": "2026-08-28",
          "quantity": 1,
          "right": "put",
          "side": "sell",
          "strike": 35
        }
      ],
      "modeledEntry": 0.16,
      "modeledWinProbability": 0.6705,
      "outcome": null,
      "pickId": "01M00B1KBB9AAV6PGPMHYE4FK5",
      "profitTargets": [
        {
          "label": "1st",
          "pct": "15"
        }
      ],
      "publishedAt": "2026-08-14T14:30:16.056530+00:00",
      "right": "P",
      "status": "active",
      "stopLossPct": 10,
      "strategy": "bull-put-spread",
      "strike": 34.5,
      "symbol": "IBIT"
    },
    {
      "desk": "hedge-desk",
      "dteAtPublish": 29,
      "expiry": "2026-09-11",
      "legs": [
        {
          "expiry": "2026-09-11",
          "quantity": 1,
          "right": "stock",
          "side": "buy",
          "strike": 0
        },
        {
          "expiry": "2026-09-11",
          "quantity": 1,
          "right": "put",
          "side": "buy",
          "strike": 210
        }
      ],
      "modeledEntry": 228.805,
      "modeledWinProbability": 0.4271,
      "outcome": null,
      "pickId": "01M00B1CEPKM5KV6T2T02TGA3E",
      "profitTargets": [
        {
          "label": "1st",
          "pct": "9.17"
        }
      ],
      "publishedAt": "2026-08-14T14:30:16.056530+00:00",
      "right": "P",
      "status": "active",
      "stopLossPct": null,
      "strategy": "married-put",
      "strike": 210,
      "symbol": "NVDA"
    },
    {
      "desk": "vol-breakout",
      "dteAtPublish": 15,
      "expiry": "2026-08-28",
      "legs": [
        {
          "expiry": "2026-08-28",
          "quantity": 1,
          "right": "call",
          "side": "buy",
          "strike": 18
        },
        {
          "expiry": "2026-08-28",
          "quantity": 1,
          "right": "put",
          "side": "buy",
          "strike": 18
        }
      ],
      "modeledEntry": 1.365,
      "modeledWinProbability": 0.4256,
      "outcome": null,
      "pickId": "01M00B198HVMBD7HGNVJJ2H6KS",
      "profitTargets": [
        {
          "label": "1st",
          "pct": "50.18"
        }
      ],
      "publishedAt": "2026-08-14T14:30:16.056530+00:00",
      "right": "C",
      "status": "active",
      "stopLossPct": 50.18,
      "strategy": "long-straddle",
      "strike": 18,
      "symbol": "SOFI"
    }
  ],
  "meta": {
    "dataset": "desk",
    "cursor": null
  }
}

No request leaves your browser. These are real responses this endpoint has returned, recorded and filtered locally.

GET/data/plays

Surfaced plays

The structures the ranking surfaced on a given session.

Requires the read:plays scope.

`scoreBand` is a band rather than the number on purpose: a ranked board plus its factors is a linear system a reader can solve for the weight vector.

Parameters

limitintegerdefault 100: Rows, 1-500.
cursorstring: Page cursor.
dateYYYYMMDD or YYYY-MM-DDdefault today (UTC): Session to return. Floored to your tier's lookback.
symbolstring: Filter to one underlying.

Response fields

playIdstringStable identifier.

symbolstringUnderlying.

strategystringStructure name.

variantstringWhich board surfaced it.

legsarrayside, right, strike, expiry, quantity per leg.

expirationstringStructure expiry.

surfacedAtstringWhen it entered the board.

firstSurfacedAtstringFirst time it ever surfaced.

lastSeenAtstringMost recent appearance.

reSurfaceCountnumberHow many times it has re-entered.

scoreBandstringA coarse band. The raw score is never served.

modeledWinProbabilitynumberModelled probability of profit.

whySurfacedstringThe reason it cleared the board's rule.

statusstringLifecycle state.

managedExitobject | nulltakeProfitPct, stopLossPct, maxHoldDays when the structure carries one.

Test it outRecorded · 2026-08-15

limitcursordatesymbol

GET https://api.hedg3.ai/v1/data/plays?limit=3&date=2026-08-12&symbol=CSCO

Response

200 · 1 row

{
  "data": [
    {
      "expiration": "2026-09-18",
      "firstSurfacedAt": "2026-08-15T05:30:06.683526+00:00",
      "lastSeenAt": null,
      "legs": [
        {
          "expiry": "2026-08-21",
          "quantity": 1,
          "right": "call",
          "side": "sell",
          "strike": 113
        },
        {
          "expiry": "2026-09-18",
          "quantity": 1,
          "right": "call",
          "side": "buy",
          "strike": 110
        }
      ],
      "managedExit": null,
      "modeledWinProbability": 0.9978,
      "playId": "fe90cf0b5dc964db",
      "reSurfaceCount": 0,
      "scoreBand": "80",
      "status": "open",
      "strategy": "call-diagonal",
      "surfacedAt": "2026-08-15T05:30:06.683526+00:00",
      "symbol": "CSCO",
      "variant": "base",
      "whySurfaced": null
    }
  ],
  "meta": {
    "dataset": "plays",
    "cursor": null
  }
}

No request leaves your browser. These are real responses this endpoint has returned, recorded and filtered locally.

GET/data/regime

Positioning regime

The dealer-positioning regime label and its key strikes for one underlying.

Requires the read:regime scope.

Without `since` this returns exactly one row and meta.cursor: null.
Net gamma and spot are deliberately not served.
`maxPainStrike` is null rather than degraded when the settled row it needs does not exist.

Parameters

symbolstringrequired: REQUIRED. Omitting it returns 400. This route has no market-wide mode.
sincestring (YYYY-MM-DD): Switches to the dated archive. Omit for the latest single row.
limitintegerdefault 100: Archive mode only.
cursorstring: Archive mode only.

Response fields

symbolstringUnderlying.

regimestringThe regime label.

zeroGammaStrikenumberThe flip level, when one is measurable in-band.

callWallStrikenumberHeaviest call-side strike.

putWallStrikenumberHeaviest put-side strike.

maxPainStrikenumberFrom the prior session's settled open interest, with its OWN vintage.

sessionDatestringSession the levels belong to.

asOfstringThe DATUM's own timestamp, never a fetch time.

resolutionstringintraday | closing | eod.

vintageobjectPer-section as-of: levels and maxPain each carry their own, because they can differ.

Test it outRecorded · 2026-08-15

symbolreqsincelimitcursor

GET https://api.hedg3.ai/v1/data/regime?symbol=SPY&limit=1

Response

200 · 1 row

{
  "data": [
    {
      "asOf": "2026-08-15T05:30:06.683526+00:00",
      "callWallStrike": 780,
      "maxPainStrike": 775,
      "putWallStrike": 765,
      "regime": "long_gamma",
      "resolution": "eod",
      "sessionDate": "2026-08-14",
      "symbol": "SPY",
      "vintage": {
        "levels": {
          "asOf": "2026-08-15T05:30:06.683526+00:00",
          "resolution": "eod",
          "sessionDate": "2026-08-14"
        },
        "maxPain": {
          "asOf": "2026-08-15T05:30:06.683526+00:00",
          "resolution": "eod",
          "sessionDate": "2026-08-14"
        }
      },
      "zeroGammaStrike": 779.9
    }
  ],
  "meta": {
    "dataset": "regime",
    "cursor": null
  }
}

No request leaves your browser. These are real responses this endpoint has returned, recorded and filtered locally.

GET/data/unusual

Flagged unusual activity

Options activity that cleared the unusual-activity trigger on a session.

Requires the read:unusual scope.

There is no symbol filter on this route.
Premium is served as a band. The raw figure is never emitted.
Direction and action are INFERRED from where the print landed. No exchange publishes the side of an options trade.

Parameters

limitintegerdefault 100: Rows, 1-500.
cursorstring: Page cursor.
dateYYYYMMDD or YYYY-MM-DDdefault today (UTC): Session to return.

Response fields

eventIdstringStable identifier.

symbolstringUnderlying.

rightstringcall | put.

strikenumberStrike.

expirystringExpiry.

dtenumberDays to expiry at the flag.

directionstringInferred direction.

actionstringInferred aggressor action.

flowTypestringblock | sweep | split.

aggressorConfidencestringHow confidently the side was inferred.

premiumBandstringA BAND, not an amount: under-100k through over-10m, or null.

flaggedAtstringWhen it cleared the trigger.

Test it outRecorded · 2026-08-15

limitcursordate

GET https://api.hedg3.ai/v1/data/unusual?limit=3&date=2026-08-12

Response

200 · 3 rows

{
  "data": [
    {
      "action": "BUY",
      "aggressorConfidence": "HIGH",
      "direction": "BULLISH",
      "dte": 14,
      "eventId": "b5d523f889c942ed",
      "expiry": "2026-08-28",
      "flaggedAt": "2026-08-14T14:22:58.076247+00:00",
      "flowType": "BLOCK",
      "premiumBand": "5m-10m",
      "right": "C",
      "strike": 765,
      "symbol": "QQQ"
    },
    {
      "action": "BUY",
      "aggressorConfidence": "HIGH",
      "direction": "BEARISH",
      "dte": 14,
      "eventId": "287cf65995cc40ee",
      "expiry": "2026-08-28",
      "flaggedAt": "2026-08-14T14:01:00.797203+00:00",
      "flowType": "BLOCK",
      "premiumBand": "1m-5m",
      "right": "P",
      "strike": 175,
      "symbol": "WDAY"
    },
    {
      "action": "BUY",
      "aggressorConfidence": "HIGH",
      "direction": "BULLISH",
      "dte": 14,
      "eventId": "0b9fa9939fd146ba",
      "expiry": "2026-08-28",
      "flaggedAt": "2026-08-14T19:09:21.328208+00:00",
      "flowType": "BLOCK",
      "premiumBand": "1m-5m",
      "right": "C",
      "strike": 62,
      "symbol": "XLE"
    }
  ],
  "meta": {
    "dataset": "unusual",
    "cursor": null
  }
}

No request leaves your browser. These are real responses this endpoint has returned, recorded and filtered locally.

Introspection

GET/data/meta/usage

Your usage

Tier, limits and what is left today.

This route is NOT charged against your daily quota, so a client can poll it to stay inside the limit without spending the limit.
This endpoint and /data/meta/datasets return a BARE object with no data/meta envelope.
current.remainingToday is null when the tier has no daily cap.

Response fields

tierstringYour key's tier.

limitsobjectrequestsPerMinute, requestsPerDay, lookbackDays.

currentobjectthisMinute, today, remainingToday.

scopesarrayThe scopes this key carries.

Test it outRecorded · 2026-08-15

No parameters.

GET https://api.hedg3.ai/v1/data/meta/usage

Response

200

{
  "tier": "advanced",
  "limits": {
    "requestsPerMinute": 120,
    "requestsPerDay": 50000,
    "lookbackDays": 90
  },
  "current": {
    "thisMinute": 3,
    "today": 412,
    "remainingToday": 49588
  },
  "scopes": [
    "read:insiders",
    "…"
  ]
}

No request leaves your browser. Your parameters build the request line; the response is a recorded sample of this endpoint’s shape.

GET/data/meta/datasets

Dataset catalogue

The public-record datasets and whether each is currently available.

The catalogue lists the eight public-record datasets only. The hedg3-output routes are not enumerated there; read them from this reference.

Response fields

datasets[].namestringDataset key.

datasets[].scopestringThe scope a key needs.

datasets[].descriptionstringOne line.

datasets[].availablebooleanWhether it is being served.

Test it outRecorded · 2026-08-15

No parameters.

GET https://api.hedg3.ai/v1/data/meta/datasets

Response

200

{
  "datasets": [
    {
      "name": "congress",
      "scope": "read:congress",
      "description": "…",
      "available": true
    }
  ]
}

No request leaves your browser. Your parameters build the request line; the response is a recorded sample of this endpoint’s shape.

API access is licensed for use inside your own application and may not be redistributed or resold. The API returns general, non-personalized market data. See Disclosures for sourcing, latency and limitations.