every edgeful plan includes API access. the essentials plan gives you a starter setup (3 reports, a small set of test tickers, 6-month lookback), pro and all-access unlock the full catalog. 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 a list of your existing keys (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 sk_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.

name your keys well

keys aren't expensive — make as many as you need. one key per integration is the cleanest setup:

one key per environment — separate keys for dev, staging, and production
one key per integration — separate keys for your Claude desktop setup, your custom dashboard, your morning digest script
use descriptive names that tell future-you what the key does the dashboard shows the masked prefix next to each name, so if you ever see a 401 error, you can tell at a glance which key the integration is trying to use.

rotate keys when you need to

key management lives under Settings → API Keys. each existing 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

multiple active keys are supported, so you can stage a rotation cleanly: generate the new key, deploy it to your integration, watch the traffic move over, then regenerate the old key once you're confident nothing's still using it.

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 .env file and load it — don't paste the key directly into a cell
if 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.

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 the report's computed stats and a per-day detail table. the exact shape varies per endpoint — the docs' Try it panel on each report's reference page shows the live response for that endpoint. as a sketch of what gap-fill-standard returns:

{  "summary": {    "gap_up_count": 134,    "gap_down_count": 118,    "gap_up_fill_pct": 64.2,    "gap_down_fill_pct": 57.6  },  "per_day": [    { "date": "2024-01-02", "gap_type": "up",   "gap_size": 0.42, "filled": true,  "fill_time": "10:14" },    { "date": "2024-01-03", "gap_type": "down", "gap_size": 0.18, "filled": false, "fill_time": null    }  ]}

illustrative shape only — field names vary by report. always check the exact response in the docs' Try it panel for the specific endpoint you're calling.

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 opening range breakout, IB, ORB), 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.

getting your first API key