every edgeful plan includes API access. on essential, that's a starter set — 3 reports (opening stats, green & red days by weekday, and previous day's range), 4 test tickers (RTY, AAPL, ETHUSDT, GBPCAD), 6 months of history, and summary data only. pro and all-access open up every report and ticker, all available history, per-day detail, and live data. either way, the first step is the same — generate a key in the API dashboard.
if you've never written code before and you'd rather have Claude Code wire everything up for you, see the no-code walkthrough with VS Code + Claude Code — it covers the same key generation flow below, plus how to pull data without writing requests by hand.
generate your first key
your keys live under API dashboard → API Keys in the edgeful app.
open API dashboard → API Keys.
you'll see your existing key, if you have one (empty if this is your first time).
click generate API key, give it a descriptive name (something like
local-dev,claude, or the name of the integration), and copy the plaintext value.
a few important things about that plaintext value:
the key value starts with
ef_live_followed by a random string. copy the whole thing — both the prefix and the random part.it's only shown to you once — at creation. after that, the dashboard only displays a short masked prefix so you can identify which key is which.
if you lose it, you can't recover it. you'll need to generate a new one.
copy it directly into your environment variable or secret manager before navigating away from the page.
one key per account
your account has one active API key at a time. every integration you run — your Claude desktop setup, your custom dashboard, your morning digest script — authenticates with that same key, so store it in one place (an environment variable or secret manager) and point each integration at it.
give the key a descriptive name anyway. the dashboard shows the masked prefix next to it, so if you ever see a 401 you can confirm at a glance that your integration is using the current value and not one you've since regenerated.
one thing that trips people up: the key carries your plan tier and rate limits. there's no per-key tier. to change what the key can pull, you change your plan, not the key.
rotate keys when you need to
key management lives on the same API dashboard → API Keys page. your key has 2 actions:
rename key — change the label. doesn't affect the key value or anything that's authenticating with it.
regenerate key — issues a new value for the same key slot. the old value stops working immediately. when to rotate:
you suspect a key was exposed (committed to a repo, posted in a screenshot, shared in a chat)
someone with access to the key value left the team or no longer needs it
on whatever schedule your security policy requires
because there's one active key per account, a rotation is a cutover, not a staged handoff: the moment you regenerate, the old value stops authenticating everywhere. have your integrations ready to take the new value, regenerate, then update each one straight away.
there's no automatic expiry on edgeful API keys — rotation is manual.
storing keys safely
a few rules that prevent every common mistake:
store keys in environment variables or a secret manager — never in code, never in the repo
never commit a key to source control, even in a private repo
mask keys in any logs. the last 4 characters is plenty to identify which key was used in a request
if you're prototyping in a notebook, use a
.envfile and load it — don't paste the key directly into a cellif you're sharing code with someone, double-check the file for hardcoded keys before sending. if you do accidentally expose a key, even briefly, the right move is to regenerate it from the dashboard immediately. that invalidates the exposed value and you can deploy the new one.
what you can do once you have a key
every report on edgeful — gap fill, ORB, IB, ADR, outside days, all of them — is powered by an underlying calculation endpoint. once you have a key, you can call those endpoints directly.
on essential? the gap fill and ORB examples below need pro or above. essential keys can call 3 reports — opening stats, green & red days by weekday, and previous day's range — on 4 tickers (RTY, AAPL, ETHUSDT, GBPCAD). calling anything outside that set returns a 403. to try the flow on essential, swap in a report and ticker you have access to, like previous-days-range/stock/AAPL.
here's a working example using gap fill standard for SPY:
curl -H "Authorization: Bearer $EDGEFUL_API_KEY" \ "https://api.edgeful.com/report_calculation/gap-fill-standard/stock/SPY?start_date=2024-01-01&end_date=2024-12-31"
python
import os
import requests
url = "https://api.edgeful.com/report_calculation/gap-fill-standard/stock/SPY"
headers = {"Authorization": f"Bearer {os.environ['EDGEFUL_API_KEY']}"}
params = {"start_date": "2024-01-01", "end_date": "2024-12-31"}
response = requests.get(url, headers=headers, params=params)
response.raise_for_status()
data = response.json()
javascript
const url = "https://api.edgeful.com/report_calculation/gap-fill-standard/stock/SPY";
const params = new URLSearchParams({
start_date: "2024-01-01",
end_date: "2024-12-31"
});
const response = await fetch(url + "?" + params, {
headers: { Authorization: "Bearer " + process.env.EDGEFUL_API_KEY }
});
if (!response.ok) throw new Error("HTTP " + response.status);
const data = await response.json();
all three snippets read the key from an EDGEFUL_API_KEY environment variable — that keeps the plaintext value out of your code. python's response.raise_for_status() and the JavaScript response.ok check both throw on a non-2xx response so you catch errors early; drop those lines if you'd rather inspect the status code yourself.
prefer not to write any of this by hand? the VS Code + Claude Code walkthrough shows how to pull the same data by asking in plain english — no curl, no python, no javascript required.
what comes back
a successful call returns a JSON body with two parts. the summary holds the report's computed stats — the counts of how often each condition occurred, plus those counts as percentages. it's the same data you see at the top of the report in the app. the per-day detail is a row for each day in your date range showing what happened that session.
per-day detail rows are included on pro and all-access, which unlock the row-level dataset. essential returns the summary stats only.
exact field names depend on the report — a gap report returns gap and fill fields, an IB report returns breakout fields, and so on. the docs' Try it panel on each report's reference page shows the live response for that specific endpoint, so you can see the exact shape before you write any code.
now with intraday session params
gap fill is a daily-shape report — it doesn't need intraday params. once you move to intraday reports (anything under intraday_calculation like ORB and IB), every call needs 3 more parameters: start_time, end_time, and timezone. these aren't free-form — they're canonical presets per market_type and session.
here's the docs' quickstart example — opening range breakout standard for ES futures, NY session:
curl -H "Authorization: Bearer $EDGEFUL_API_KEY" \ "https://api.edgeful.com/intraday_calculation/opening-range-breakout-standard/futures/ES?start_date=2024-01-01&end_date=2024-01-31&start_time=09:30:00&end_time=16:00:00&timezone=America/New_York"
the canonical session values per market_type live on the session presets docs page — use those exactly. for the full list of intraday endpoints, see the API reference.
live data endpoints
the report_calculation and intraday_calculation endpoints above return calculated stats over a historical date range. edgeful also exposes a separate live data category — the same data behind the in-app what's in play dashboard and the screener page. live data endpoints are listed in the live data section of the API reference sidebar.
live data is only available on the pro and all-access tiers — essentials API access is restricted to historical report calculations.
what's available to you depends on your plan tier — the rate limits + tier differences covers the full breakdown.
for the complete endpoint catalog, parameters, and response shapes, the API reference is the source of truth: https://www.edgeful.com/docs/api-reference. for header format, key format, and rotation details, see the authentication docs.