API reference

Thirteen endpoints across scores, discovery, outcomes, account, and quant delivery. Costs shown are live rate-card values; tier badges mark plan-gated endpoints.

Scores & history

GET /v1/scores/{ticker} 2 creditsTry it →

Latest Main Street / Wall Street / LikeFolio Score for one ticker.

Free keys: 7-day delayed data, top-100 coverage. Pro-member keys: live, full universe.

Param	In	Type	Description
`ticker` *	path	string	US stock symbol (max 12 chars, case-insensitive).

curlPythonJavaScript

curl -H "X-API-Key: lf_your_key" \
  "https://likefolio.ai/v1/scores/AAPL"

import requests

r = requests.get(
    "https://likefolio.ai/v1/scores/AAPL",
    headers={"X-API-Key": "lf_your_key"},
)
r.raise_for_status()
print(r.json(), "|", r.headers.get("X-Credits-Remaining"), "credits left")

const r = await fetch(
  "https://likefolio.ai/v1/scores/AAPL",
  { headers: { "X-API-Key": "lf_your_key" } });
const data = await r.json();
console.log(data, "|", r.headers.get("X-Credits-Remaining"), "credits left");

Response field	Meaning
`ticker`	the requested symbol
`date`	score date (equals as_of)
`main_street`	0-100 measured consumer demand
`wall_street`	0-100 analyst sentiment
`likefolio_score`	0-100 composite
`divergence_gap`	main_street - wall_street (null if either missing)
`estimated`	true = model-backfilled row (provenance flag)
`as_of`	data as-of date (free tier trails 7 days)
`citation_url`	canonical page to cite

Example response

{
  "ticker": "AAPL",
  "date": "2026-06-30",
  "main_street": 71,
  "wall_street": 58,
  "likefolio_score": 66,
  "estimated": false,
  "divergence_gap": 13,
  "as_of": "2026-06-30",
  "source": "LikeFolio consumer-demand data",
  "citation_url": "https://likefolio.ai/stock/AAPL"
}

Errors: 401 · 403-key · 403-coverage · 404 · 429

MCP twin: get_scores — same credits, same data. MCP guide →

GET /v1/scores/{ticker}/history 1 creditTry it →

Daily score history for one ticker. Depth is tier-bound and dates clamp silently to your floor.

History floor by tier: free 90 days, Pro-member 365, hobbyist 3 years, builder+ full (2016+). `start` is clamped to the floor and `end` to your as-of date — check `history_floor` in the response.

Param	In	Type	Description
`ticker` *	path	string	US stock symbol.
`start`	query	date	YYYY-MM-DD; clamped to your tier's history floor.
`end`	query	date	YYYY-MM-DD; clamped to your as-of date.

curlPythonJavaScript

curl -H "X-API-Key: lf_your_key" \
  "https://likefolio.ai/v1/scores/AAPL/history?start=2026-01-01&end=2026-06-30"

import requests

r = requests.get(
    "https://likefolio.ai/v1/scores/AAPL/history",
    headers={"X-API-Key": "lf_your_key"},
    params={'start': '2026-01-01', 'end': '2026-06-30'},
)
r.raise_for_status()
print(r.json(), "|", r.headers.get("X-Credits-Remaining"), "credits left")

const r = await fetch(
  "https://likefolio.ai/v1/scores/AAPL/history?start=2026-01-01&end=2026-06-30",
  { headers: { "X-API-Key": "lf_your_key" } });
const data = await r.json();
console.log(data, "|", r.headers.get("X-Credits-Remaining"), "credits left");

Response field	Meaning
`ticker`	the requested symbol
`rows`	[{date, main_street, wall_street, likefolio_score, estimated}]
`count`	number of rows returned
`history_floor`	the effective start date after tier clamping
`provenance_note`	history methodology statement

Example response

{
  "ticker": "AAPL",
  "count": 2,
  "history_floor": "2026-04-01",
  "rows": [
    {
      "date": "2026-06-27",
      "main_street": 70,
      "wall_street": 57,
      "likefolio_score": 65,
      "estimated": false
    },
    {
      "date": "2026-06-30",
      "main_street": 71,
      "wall_street": 58,
      "likefolio_score": 66,
      "estimated": false
    }
  ],
  "as_of": "2026-06-30",
  "citation_url": "https://likefolio.ai/stock/AAPL"
}

Errors: 400 · 401 · 403-key · 403-coverage · 429

MCP twin: get_score_history — same credits, same data. MCP guide →

GET /v1/scores/social-heat/{ticker} 1 creditTry it →

Visits-based Social Heat Score history, computed on the fly from currently stored SimilarWeb US visits.

Same tier history floors as /scores/{ticker}/history. SimilarWeb revises past visits, so values for old dates differ from Social Heat as originally served — this endpoint makes no historical-accuracy claim (see `provenance_note`).

Param	In	Type	Description
`ticker` *	path	string	US stock symbol.
`start`	query	date	YYYY-MM-DD; clamped to your tier's history floor.
`end`	query	date	YYYY-MM-DD; clamped to your as-of date.

curlPythonJavaScript

curl -H "X-API-Key: lf_your_key" \
  "https://likefolio.ai/v1/scores/social-heat/AAPL?start=2026-01-01&end=2026-06-30"

import requests

r = requests.get(
    "https://likefolio.ai/v1/scores/social-heat/AAPL",
    headers={"X-API-Key": "lf_your_key"},
    params={'start': '2026-01-01', 'end': '2026-06-30'},
)
r.raise_for_status()
print(r.json(), "|", r.headers.get("X-Credits-Remaining"), "credits left")

const r = await fetch(
  "https://likefolio.ai/v1/scores/social-heat/AAPL?start=2026-01-01&end=2026-06-30",
  { headers: { "X-API-Key": "lf_your_key" } });
const data = await r.json();
console.log(data, "|", r.headers.get("X-Credits-Remaining"), "credits left");

Response field	Meaning
`ticker`	the requested symbol
`metric`	always 'social_heat_live'
`formula`	visits / max(visits, trailing 365 calendar days) * 100
`rows`	[{date, value}] — value is 0–100, 2dp
`count`	number of rows returned
`history_floor`	the effective start date after tier clamping
`provenance_note`	live-computation disclaimer

Example response

{
  "ticker": "AAPL",
  "metric": "social_heat_live",
  "count": 2,
  "formula": "visits / max(visits, trailing 365 calendar days) * 100",
  "history_floor": "2026-04-01",
  "rows": [
    {
      "date": "2026-06-29",
      "value": 71.4
    },
    {
      "date": "2026-06-30",
      "value": 73.02
    }
  ],
  "as_of": "2026-06-30",
  "citation_url": "https://likefolio.ai/social-heat/AAPL"
}

Errors: 400 · 401 · 403-key · 403-coverage · 404 · 429

GET /v1/scores/history 1 creditTry it →

Daily score history for many tickers in one call, at the same per-row rate as the single-ticker route. Use `since` to pull only rows written or RESTATED since your last sync.

History depth is tier-entitled (free 90d, hobbyist 3yr, builder+ full) and free keys are fenced to the top 100, exactly as on /v1/scores/{ticker}/history. Max 50 tickers per call — page the list.

Param	In	Type	Description
`tickers`	query	string	Comma-separated, max 50. Omit for everything the key can see.
`start`	query	date	YYYY-MM-DD, floored at your tier's history depth.
`end`	query	date	YYYY-MM-DD, capped at your tier's as-of date.
`since`	query	date	Filters on when a row was WRITTEN, not its date — returns rows that are new or have been restated.

curlPythonJavaScript

curl -H "X-API-Key: lf_your_key" \
  "https://likefolio.ai/v1/scores/history"

import requests

r = requests.get(
    "https://likefolio.ai/v1/scores/history",
    headers={"X-API-Key": "lf_your_key"},
)
r.raise_for_status()
print(r.json(), "|", r.headers.get("X-Credits-Remaining"), "credits left")

const r = await fetch(
  "https://likefolio.ai/v1/scores/history",
  { headers: { "X-API-Key": "lf_your_key" } });
const data = await r.json();
console.log(data, "|", r.headers.get("X-Credits-Remaining"), "credits left");

Response field	Meaning
`rows`	[{ticker, date, main_street, wall_street, likefolio_score, divergence_gap, estimated, restated_at}]
`count`	number of rows returned (what you are billed for)
`restated_at`	when this row was last written. Score history is restated deliberately; compare against your stored copy to detect corrections.

Example response

{
  "rows": [
    {
      "ticker": "AAPL",
      "date": "2026-08-01",
      "main_street": 89.0,
      "wall_street": 59.0,
      "likefolio_score": 88.37,
      "divergence_gap": 30.0,
      "estimated": false,
      "restated_at": "2026-08-01 06:12:03"
    }
  ],
  "count": 1,
  "tickers": 1,
  "start": "2026-08-01",
  "end": "2026-08-01",
  "since": null,
  "as_of": "2026-08-27",
  "citation_url": "https://likefolio.ai/developers"
}

Errors: 400 · 401 · 403-key · 429

Discovery

GET /v1/screener 2 creditsTry it →

The whole universe, ranked by LikeFolio Score, filterable by score floor.

Free keys see only top-100-coverage rows — `count` can come back well under `limit`.

Param	In	Type	Description
`min_score`	query	integer	Only rows with likefolio_score >= this.
`limit`	query	integer	Max rows (values above 650 return 422). Default 100.

curlPythonJavaScript

curl -H "X-API-Key: lf_your_key" \
  "https://likefolio.ai/v1/screener?min_score=80&limit=25"

import requests

r = requests.get(
    "https://likefolio.ai/v1/screener",
    headers={"X-API-Key": "lf_your_key"},
    params={'min_score': 80, 'limit': 25},
)
r.raise_for_status()
print(r.json(), "|", r.headers.get("X-Credits-Remaining"), "credits left")

const r = await fetch(
  "https://likefolio.ai/v1/screener?min_score=80&limit=25",
  { headers: { "X-API-Key": "lf_your_key" } });
const data = await r.json();
console.log(data, "|", r.headers.get("X-Credits-Remaining"), "credits left");

Response field	Meaning
`rows`	[{ticker, date, main_street, wall_street, likefolio_score, divergence_gap}] ranked by score desc
`count`	rows returned after tier coverage filtering

Example response

{
  "rows": [
    {
      "ticker": "NVDA",
      "date": "2026-06-30",
      "main_street": 88,
      "wall_street": 74,
      "likefolio_score": 84,
      "divergence_gap": 14
    }
  ],
  "count": 1,
  "as_of": "2026-06-30",
  "source": "LikeFolio consumer-demand data",
  "citation_url": "https://likefolio.ai/enterprise"
}

Errors: 401 · 403-key · 422 · 429

MCP twin: screen_stocks — same credits, same data. MCP guide →

GET /v1/divergence 3 creditsTry it →

Today's widest Main Street vs Wall Street gaps, ranked, with researched why-now context on builder+.

`why_now` / `why_now_headline` are builder+ fields — `why_now_included` tells you whether your tier got the research.

Param	In	Type	Description
`direction`	query	enum	bull = Main Street above Wall Street; bear = below. Case-insensitive; absent/null means all. Default all.
`limit`	query	integer	Max rows (values above 100 return 422). Default 25.

curlPythonJavaScript

curl -H "X-API-Key: lf_your_key" \
  "https://likefolio.ai/v1/divergence?direction=bull&limit=10"

import requests

r = requests.get(
    "https://likefolio.ai/v1/divergence",
    headers={"X-API-Key": "lf_your_key"},
    params={'direction': 'bull', 'limit': 10},
)
r.raise_for_status()
print(r.json(), "|", r.headers.get("X-Credits-Remaining"), "credits left")

const r = await fetch(
  "https://likefolio.ai/v1/divergence?direction=bull&limit=10",
  { headers: { "X-API-Key": "lf_your_key" } });
const data = await r.json();
console.log(data, "|", r.headers.get("X-Credits-Remaining"), "credits left");

Response field	Meaning
`rows`	[{ticker, company, main_street, wall_street, gap, percentile, days_at_extreme, why_now?, why_now_headline?}]
`count`	rows returned
`why_now_included`	whether your tier received the research fields

Example response

{
  "rows": [
    {
      "ticker": "CMG",
      "company": "Chipotle",
      "main_street": 82,
      "wall_street": 41,
      "gap": 41,
      "percentile": 0.97,
      "days_at_extreme": 6
    }
  ],
  "count": 1,
  "why_now_included": false,
  "as_of": "2026-06-30",
  "citation_url": "https://likefolio.ai/research/divergence"
}

Errors: 400 · 401 · 403-key · 422 · 429

MCP twin: get_divergences — same credits, same data. MCP guide →

GET /v1/signals 2 creditsTry it →

Recent published, ticker-tagged research signals (delayed on free keys).

Param	In	Type	Description
`limit`	query	integer	Max rows (values above 200 return 422). Default 50.

curlPythonJavaScript

curl -H "X-API-Key: lf_your_key" \
  "https://likefolio.ai/v1/signals?limit=10"

import requests

r = requests.get(
    "https://likefolio.ai/v1/signals",
    headers={"X-API-Key": "lf_your_key"},
    params={'limit': 10},
)
r.raise_for_status()
print(r.json(), "|", r.headers.get("X-Credits-Remaining"), "credits left")

const r = await fetch(
  "https://likefolio.ai/v1/signals?limit=10",
  { headers: { "X-API-Key": "lf_your_key" } });
const data = await r.json();
console.log(data, "|", r.headers.get("X-Credits-Remaining"), "credits left");

Response field	Meaning
`signals`	[{id, alert_type, content, tickers, themes, created_at}]
`count`	signals returned

Example response

{
  "signals": [
    {
      "id": 9184,
      "alert_type": "demand_shift",
      "content": "Wingstop web visits +38% YoY\u2026",
      "tickers": [
        "WING"
      ],
      "themes": [
        "fast-casual"
      ],
      "created_at": "2026-06-29 14:02:11"
    }
  ],
  "count": 1,
  "as_of": "2026-06-30",
  "citation_url": "https://likefolio.ai/enterprise"
}

Errors: 401 · 403-key · 422 · 429

GET /v1/themes 2 creditsTry it →

Curated investment theme baskets with aggregate demand scores.

curlPythonJavaScript

curl -H "X-API-Key: lf_your_key" \
  "https://likefolio.ai/v1/themes"

import requests

r = requests.get(
    "https://likefolio.ai/v1/themes",
    headers={"X-API-Key": "lf_your_key"},
)
r.raise_for_status()
print(r.json(), "|", r.headers.get("X-Credits-Remaining"), "credits left")

const r = await fetch(
  "https://likefolio.ai/v1/themes",
  { headers: { "X-API-Key": "lf_your_key" } });
const data = await r.json();
console.log(data, "|", r.headers.get("X-Credits-Remaining"), "credits left");

Response field	Meaning
`themes`	[{slug, name, description, strength, stock_count, tickers[], avg_main_street, avg_wall_street, avg_likefolio_score, scored_count}] — aggregates are computed from each constituent's latest scores (delay-aware on the free tier)
`count`	themes returned

Example response

{
  "themes": [
    {
      "slug": "glp-1",
      "name": "GLP-1 economy",
      "stock_count": 14,
      "strength": 0.72,
      "tickers": [
        "LLY",
        "NVO",
        "HIMS"
      ],
      "avg_main_street": 66,
      "avg_wall_street": 58,
      "avg_likefolio_score": 63,
      "scored_count": 14,
      "description": "Winners and losers of appetite suppression."
    }
  ],
  "count": 1,
  "as_of": "2026-07-01",
  "citation_url": "https://likefolio.ai/enterprise"
}

Errors: 401 · 403-key · 429

GET /v1/themes/{slug} 1 credit

One theme with every constituent's latest scores and divergence gap. Billed 1 credit per constituent returned.

1 credit per constituent returned. Free keys get scores only for top-100-coverage constituents; uncovered tickers stay listed with null scores.

Param	In	Type	Description
`slug` *	path	string	Theme slug from GET /v1/themes.

curlPythonJavaScript

curl -H "X-API-Key: lf_your_key" \
  "https://likefolio.ai/v1/themes/glp-1"

import requests

r = requests.get(
    "https://likefolio.ai/v1/themes/glp-1",
    headers={"X-API-Key": "lf_your_key"},
)
r.raise_for_status()
print(r.json(), "|", r.headers.get("X-Credits-Remaining"), "credits left")

const r = await fetch(
  "https://likefolio.ai/v1/themes/glp-1",
  { headers: { "X-API-Key": "lf_your_key" } });
const data = await r.json();
console.log(data, "|", r.headers.get("X-Credits-Remaining"), "credits left");

Response field	Meaning
`constituents`	[{ticker, relationship, date, main_street, wall_street, likefolio_score, divergence_gap}]
`avg_main_street`	aggregate over scored constituents
`scored_count`	how many constituents the aggregates cover

Example response

{
  "slug": "glp-1",
  "name": "GLP-1 economy",
  "strength": 0.72,
  "stock_count": 14,
  "scored_count": 14,
  "avg_main_street": 66,
  "avg_wall_street": 58,
  "avg_likefolio_score": 63,
  "constituents": [
    {
      "ticker": "LLY",
      "relationship": "Strong",
      "date": "2026-07-01",
      "main_street": 74,
      "wall_street": 66,
      "likefolio_score": 71,
      "divergence_gap": 8
    }
  ],
  "as_of": "2026-07-01",
  "citation_url": "https://likefolio.ai/themes/glp-1"
}

Errors: 401 · 403-key · 404 · 429

GET /v1/coverage freeTry it →

Every ticker this key can currently retrieve a score for — the /v1 replacement for the old charts endpoint /charts/v1/companies/with-social-heat-score. Free, so discovering coverage never costs credits.

Scoped to the caller: free keys list the top 100 by LikeFolio Score and read 7 days delayed, so the manifest never names a ticker that key would 403 or cannot see yet. Paid keys list the full universe.

Param	In	Type	Description
`since`	query	date	YYYY-MM-DD — return only tickers scored on or after this date. The cheap daily delta.

curlPythonJavaScript

curl -H "X-API-Key: lf_your_key" \
  "https://likefolio.ai/v1/coverage"

import requests

r = requests.get(
    "https://likefolio.ai/v1/coverage",
    headers={"X-API-Key": "lf_your_key"},
)
r.raise_for_status()
print(r.json(), "|", r.headers.get("X-Credits-Remaining"), "credits left")

const r = await fetch(
  "https://likefolio.ai/v1/coverage",
  { headers: { "X-API-Key": "lf_your_key" } });
const data = await r.json();
console.log(data, "|", r.headers.get("X-Credits-Remaining"), "credits left");

Response field	Meaning
`tickers`	sorted list of ticker symbols
`count`	len(tickers)
`coverage`	'all' or 'top100' — which universe this key sees
`since`	echo of the since filter, or null

Example response

{
  "tickers": [
    "AAPL",
    "ABNB",
    "AMD"
  ],
  "count": 3,
  "coverage": "all",
  "since": null,
  "as_of": "2026-08-26",
  "citation_url": "https://likefolio.ai/developers"
}

Errors: 400 · 401 · 403-key · 429

GET /v1/earnings 100 creditsbuilder+Try it →

Covered names reporting soon, with the current demand read on each. Builder+ only.

Builder+ only — Free and Hobbyist return 403 (unbilled). Flat 100 credits per call.

Param	In	Type	Description
`days`	query	integer	Horizon in days (values above 60 return 422). Default 14.

curlPythonJavaScript

curl -H "X-API-Key: lf_your_key" \
  "https://likefolio.ai/v1/earnings?days=14"

import requests

r = requests.get(
    "https://likefolio.ai/v1/earnings",
    headers={"X-API-Key": "lf_your_key"},
    params={'days': 14},
)
r.raise_for_status()
print(r.json(), "|", r.headers.get("X-Credits-Remaining"), "credits left")

const r = await fetch(
  "https://likefolio.ai/v1/earnings?days=14",
  { headers: { "X-API-Key": "lf_your_key" } });
const data = await r.json();
console.log(data, "|", r.headers.get("X-Credits-Remaining"), "credits left");

Response field	Meaning
`reporters`	[{ticker, name, next_earnings_date, main_street, wall_street, likefolio_score}] ordered by date
`count`	reporters returned

Example response

{
  "reporters": [
    {
      "ticker": "NKE",
      "name": "Nike",
      "next_earnings_date": "2026-07-09",
      "main_street": 44,
      "wall_street": 61,
      "likefolio_score": 49
    }
  ],
  "count": 1,
  "as_of": "2026-07-01",
  "citation_url": "https://likefolio.ai/enterprise"
}

Errors: 401 · 403-key · 422 · 429

MCP twin: get_upcoming_earnings — same credits, same data. MCP guide →

Outcomes & receipts

GET /v1/divergence/events 10 creditsquant+Try it →

Dated divergence-extreme onsets with forward-return outcomes — the receipts log. Quant tier.

Quant+ only. The tier gate runs before billing: a sub-quant key pays 0 credits for the 403.

Param	In	Type	Description
`since`	query	date	YYYY-MM-DD (default: 365 days ago). Max 2,000 events, newest first.

curlPythonJavaScript

curl -H "X-API-Key: lf_your_key" \
  "https://likefolio.ai/v1/divergence/events?since=2026-01-01"

import requests

r = requests.get(
    "https://likefolio.ai/v1/divergence/events",
    headers={"X-API-Key": "lf_your_key"},
    params={'since': '2026-01-01'},
)
r.raise_for_status()
print(r.json(), "|", r.headers.get("X-Credits-Remaining"), "credits left")

const r = await fetch(
  "https://likefolio.ai/v1/divergence/events?since=2026-01-01",
  { headers: { "X-API-Key": "lf_your_key" } });
const data = await r.json();
console.log(data, "|", r.headers.get("X-Credits-Remaining"), "credits left");

Response field	Meaning
`events`	[{ticker, direction, flag_date, close_date, price_at_flag, price_at_close, pct_change, days}]
`count`	events returned

Example response

{
  "events": [
    {
      "ticker": "DKNG",
      "direction": "bull",
      "flag_date": "2026-03-02",
      "close_date": "2026-04-14",
      "price_at_flag": 41.2,
      "price_at_close": 48.9,
      "pct_change": 18.7,
      "days": 43
    }
  ],
  "count": 1,
  "as_of": "2026-07-01",
  "citation_url": "https://likefolio.ai/enterprise"
}

Errors: 400 · 401 · 403-key · 403-tier · 429

MCP twin: get_divergence_events — same credits, same data. MCP guide →

GET /v1/track-record freeTry it →

The public closed model-portfolio record — aggregate stats plus the dated per-trade list.

curlPythonJavaScript

curl -H "X-API-Key: lf_your_key" \
  "https://likefolio.ai/v1/track-record"

import requests

r = requests.get(
    "https://likefolio.ai/v1/track-record",
    headers={"X-API-Key": "lf_your_key"},
)
r.raise_for_status()
print(r.json(), "|", r.headers.get("X-Credits-Remaining"), "credits left")

const r = await fetch(
  "https://likefolio.ai/v1/track-record",
  { headers: { "X-API-Key": "lf_your_key" } });
const data = await r.json();
console.log(data, "|", r.headers.get("X-Credits-Remaining"), "credits left");

Response field	Meaning
`(stats)`	closed-trade aggregates (win rate, avg return, counts) spread at the top level
`trades`	[{ticker, direction, entry_date, exit_date, entry_price, exit_price, return_pct, days_held, win}] — return_pct is direction-adjusted

Example response

{
  "closed_trades": 148,
  "win_rate": 0.66,
  "avg_return_pct": 9.4,
  "trades": [
    {
      "ticker": "RDW",
      "direction": "long",
      "entry_date": "2026-06-30",
      "exit_date": "2026-07-13",
      "entry_price": 12.1,
      "exit_price": 9.44,
      "return_pct": -22.0,
      "days_held": 13,
      "win": false
    }
  ],
  "as_of": "2026-07-01",
  "citation_url": "https://likefolio.ai/track-record"
}

Errors: 401 · 403-key · 429

MCP twin: get_track_record — same credits, same data. MCP guide →

GET /v1/divergence/open 500 creditsquant+

Currently-open divergence extremes — the actionable signal, with flag date and entry price.

Quant only. The premium live counterpart to the retrospective /v1/divergence/events log.

curlPythonJavaScript

curl -H "X-API-Key: lf_your_key" \
  "https://likefolio.ai/v1/divergence/open"

import requests

r = requests.get(
    "https://likefolio.ai/v1/divergence/open",
    headers={"X-API-Key": "lf_your_key"},
)
r.raise_for_status()
print(r.json(), "|", r.headers.get("X-Credits-Remaining"), "credits left")

const r = await fetch(
  "https://likefolio.ai/v1/divergence/open",
  { headers: { "X-API-Key": "lf_your_key" } });
const data = await r.json();
console.log(data, "|", r.headers.get("X-Credits-Remaining"), "credits left");

Response field	Meaning
`open_trades`	[{ticker, direction, flag_date, flag_gap, price_at_flag, days_open, current_gap, current_percentile, days_at_extreme}]
`count`	open extremes returned

Example response

{
  "open_trades": [
    {
      "ticker": "INOD",
      "direction": "bull",
      "flag_date": "2026-06-30",
      "flag_gap": 78,
      "price_at_flag": 75.58,
      "days_open": 14,
      "current_gap": 78,
      "current_percentile": 0.998,
      "days_at_extreme": 10
    }
  ],
  "count": 1,
  "as_of": "2026-07-14",
  "citation_url": "https://likefolio.ai/research/divergence"
}

Errors: 401 · 403-key · 403-tier · 429

Account

GET /v1/usage freeTry it →

This key's live meter — free to call, no provenance wrapper (different shape from the data endpoints).

curlPythonJavaScript

curl -H "X-API-Key: lf_your_key" \
  "https://likefolio.ai/v1/usage"

import requests

r = requests.get(
    "https://likefolio.ai/v1/usage",
    headers={"X-API-Key": "lf_your_key"},
)
r.raise_for_status()
print(r.json(), "|", r.headers.get("X-Credits-Remaining"), "credits left")

const r = await fetch(
  "https://likefolio.ai/v1/usage",
  { headers: { "X-API-Key": "lf_your_key" } });
const data = await r.json();
console.log(data, "|", r.headers.get("X-Credits-Remaining"), "credits left");

Response field	Meaning
`tier`	the key's tier
`pro_member`	whether the Pro-member overlay is active
`monthly_allowance`	included credits (null = enterprise unmetered)
`used_this_month`	credits consumed this calendar month
`credits_remaining`	allowance - used (can be negative on overage)
`overage_credits`	credits used beyond the allowance this month
`overage_cost_usd`	accrued overage in dollars (billed per unit)
`prepaid_credits`	banked pack credits (consumed after allowance)
`allow_overage`	the hard-stop vs overage switch
`resets_at`	ISO8601 UTC when the allowance resets (month boundary)
`entitlements`	{credits, delay_days, coverage, history_days}
`rate_card`	live credit costs per endpoint (per-row for history/screener/divergence)

Example response

{
  "tier": "builder",
  "pro_member": false,
  "monthly_allowance": 30000,
  "used_this_month": 12040,
  "credits_remaining": 17960,
  "overage_credits": 0,
  "overage_cost_usd": 0.0,
  "prepaid_credits": 2000,
  "allow_overage": false,
  "overage_per_1k_usd": 3.0,
  "resets_at": "2026-08-01T00:00:00+00:00",
  "entitlements": {
    "credits": 30000,
    "delay_days": 0,
    "coverage": "all",
    "history_days": null
  },
  "rate_card": {
    "scores": 2,
    "history": 1,
    "screener": 2,
    "divergence": 3
  }
}

Errors: 401 · 403-key

GET /v1/meta freeTry it →

Machine-readable data dictionary: fields, history depth, point-in-time vintages, restatement policy, license. Free to call.

curlPythonJavaScript

curl -H "X-API-Key: lf_your_key" \
  "https://likefolio.ai/v1/meta"

import requests

r = requests.get(
    "https://likefolio.ai/v1/meta",
    headers={"X-API-Key": "lf_your_key"},
)
r.raise_for_status()
print(r.json(), "|", r.headers.get("X-Credits-Remaining"), "credits left")

const r = await fetch(
  "https://likefolio.ai/v1/meta",
  { headers: { "X-API-Key": "lf_your_key" } });
const data = await r.json();
console.log(data, "|", r.headers.get("X-Credits-Remaining"), "credits left");

Response field	Meaning
`dataset`	dataset name
`coverage`	universe statement
`fields`	per-field definitions
`history`	depth, PIT vintage stats, restatement policy
`license`	license URL
`docs`	docs URL
`mcp`	MCP URL

Example response

{
  "dataset": "LikeFolio consumer-demand scores",
  "coverage": "500+ US tickers, scored daily",
  "fields": {
    "main_street": "0-100 consumer demand"
  },
  "license": "https://likefolio.ai/developers#license",
  "docs": "https://likefolio.ai/docs",
  "mcp": "https://likefolio.ai/mcp"
}

Errors: 401 · 403-key

MCP twin: get_dataset_info — same credits, same data. MCP guide →

Quant delivery

GET /v1/bulk/exports freequant+Try it →

The nightly Backtest Pack: full score history + divergence events as gzipped CSVs with checksums. Quant tier.

Quant+ only; the listing call is free (the entitlement gate runs before billing).

curlPythonJavaScript

curl -H "X-API-Key: lf_your_key" \
  "https://likefolio.ai/v1/bulk/exports"

import requests

r = requests.get(
    "https://likefolio.ai/v1/bulk/exports",
    headers={"X-API-Key": "lf_your_key"},
)
r.raise_for_status()
print(r.json(), "|", r.headers.get("X-Credits-Remaining"), "credits left")

const r = await fetch(
  "https://likefolio.ai/v1/bulk/exports",
  { headers: { "X-API-Key": "lf_your_key" } });
const data = await r.json();
console.log(data, "|", r.headers.get("X-Credits-Remaining"), "credits left");

Response field	Meaning
`exports`	[{name, url, row_count, sha256, generated_at}] — latest bundle per export
`note`	sha256 is over the gzipped file

Example response

{
  "exports": [
    {
      "name": "score_history_full.csv.gz",
      "url": "https://\u2026",
      "row_count": 1804211,
      "sha256": "9f\u2026",
      "generated_at": "2026-07-01 06:10"
    }
  ],
  "note": "sha256 is over the gzipped file; verify after download"
}

Errors: 401 · 403-key · 403-tier · 429

POST /v1/webhooks freequant+

Quant+ only. Max 10 active webhooks per key. The secret is shown once — like API keys, it is never recoverable (which is why this endpoint is excluded from the playground).

Param	In	Type	Description
`event_type` *	body	enum	divergence_event = new extreme onsets; score_move = day-over-day \|ΔLikeFolio Score\| ≥ 10.
`url` *	body	string	Your HTTPS endpoint (https:// required).

curlPythonJavaScript

curl -X POST -H "X-API-Key: lf_your_key" \
  -H "Content-Type: application/json" \
  -d '{"event_type": "divergence_event", "url": "https://example.com/hooks/likefolio"}' \
  "https://likefolio.ai/v1/webhooks"

import requests

r = requests.post(
    "https://likefolio.ai/v1/webhooks",
    headers={"X-API-Key": "lf_your_key"},
    json={'event_type': 'divergence_event', 'url': 'https://example.com/hooks/likefolio'},
)
r.raise_for_status()
print(r.json(), "|", r.headers.get("X-Credits-Remaining"), "credits left")

const r = await fetch(
  "https://likefolio.ai/v1/webhooks",
  {
  method: "POST",
  headers: { "X-API-Key": "lf_your_key", "Content-Type": "application/json" },
  body: JSON.stringify({"event_type": "divergence_event", "url": "https://example.com/hooks/likefolio"}),
});
const data = await r.json();
console.log(data, "|", r.headers.get("X-Credits-Remaining"), "credits left");

Response field	Meaning
`id`	webhook id
`secret`	whsec_… signing secret (shown once)
`signing`	X-LikeFolio-Signature: hex(hmac_sha256(secret, raw_body))

Example response

{
  "id": 12,
  "event_type": "divergence_event",
  "url": "https://example.com/hooks/likefolio",
  "secret": "whsec_\u2026shown_once\u2026",
  "signing": "X-LikeFolio-Signature: hex(hmac_sha256(secret, raw_body))"
}

Errors: 400 · 401 · 403-key · 403-tier

GET /v1/webhooks freequant+Try it →

Your registered event webhooks with delivery health.

Endpoints auto-disable after 50 consecutive delivery failures.

curlPythonJavaScript

curl -H "X-API-Key: lf_your_key" \
  "https://likefolio.ai/v1/webhooks"

import requests

r = requests.get(
    "https://likefolio.ai/v1/webhooks",
    headers={"X-API-Key": "lf_your_key"},
)
r.raise_for_status()
print(r.json(), "|", r.headers.get("X-Credits-Remaining"), "credits left")

const r = await fetch(
  "https://likefolio.ai/v1/webhooks",
  { headers: { "X-API-Key": "lf_your_key" } });
const data = await r.json();
console.log(data, "|", r.headers.get("X-Credits-Remaining"), "credits left");

Response field	Meaning
`webhooks`	[{id, event_type, url, is_active, consecutive_failures, last_fired_at}]

Example response

{
  "webhooks": [
    {
      "id": 12,
      "event_type": "divergence_event",
      "url": "https://example.com/hooks/likefolio",
      "is_active": true,
      "consecutive_failures": 0,
      "last_fired_at": "2026-07-01 16:45:02"
    }
  ]
}

Errors: 401 · 403-key · 403-tier

DELETE /v1/webhooks/{webhook_id} freequant+

Remove one of your webhooks (destructive — excluded from the playground).

Param	In	Type	Description
`webhook_id` *	path	integer	The webhook id.

curlPythonJavaScript

curl -X DELETE -H "X-API-Key: lf_your_key" \
  "https://likefolio.ai/v1/webhooks/12"

import requests

r = requests.delete(
    "https://likefolio.ai/v1/webhooks/12",
    headers={"X-API-Key": "lf_your_key"},
)
r.raise_for_status()
print(r.json(), "|", r.headers.get("X-Credits-Remaining"), "credits left")

const r = await fetch(
  "https://likefolio.ai/v1/webhooks/12",
  { method: "DELETE", headers: { "X-API-Key": "lf_your_key" } });
const data = await r.json();
console.log(data, "|", r.headers.get("X-Credits-Remaining"), "credits left");

Response field	Meaning
`ok`	true when a row was deleted

Example response

{
  "ok": true
}

Errors: 401 · 403-key · 403-tier

POST /v1/webhooks/{webhook_id}/test freequant+

Send a signed test payload to this key's registered webhook URL and record the delivery attempt. No credits charged.

Quant+. This performs an outbound delivery; test events carry test=true.

Param	In	Type	Description
`webhook_id` *	path	integer	A webhook owned by this API key.

curlPythonJavaScript

curl -X POST -H "X-API-Key: lf_your_key" \
  -H "Content-Type: application/json" \
  -d '{}' \
  "https://likefolio.ai/v1/webhooks/12/test"

import requests

r = requests.post(
    "https://likefolio.ai/v1/webhooks/12/test",
    headers={"X-API-Key": "lf_your_key"},
    json={},
)
r.raise_for_status()
print(r.json(), "|", r.headers.get("X-Credits-Remaining"), "credits left")

const r = await fetch(
  "https://likefolio.ai/v1/webhooks/12/test",
  {
  method: "POST",
  headers: { "X-API-Key": "lf_your_key", "Content-Type": "application/json" },
  body: JSON.stringify({}),
});
const data = await r.json();
console.log(data, "|", r.headers.get("X-Credits-Remaining"), "credits left");

Response field	Meaning
`ok`	Whether delivery succeeded
`status_code`	Receiver HTTP status or null
`error`	Delivery error or null
`delivered_to`	Registered receiver URL
`signature_header`	X-LikeFolio-Signature
`payload`	Signed test event envelope

Example response

{
  "ok": true,
  "status_code": 200,
  "error": null,
  "delivered_to": "https://example.com/webhook",
  "signature_header": "X-LikeFolio-Signature",
  "payload": {
    "events": [
      {
        "type": "score_move",
        "ticker": "AAPL",
        "date": "2026-09-12",
        "likefolio_score": 72,
        "prior_score": 60,
        "delta": 12,
        "test": true
      }
    ],
    "sent_at": "2026-09-12T12:00:00Z",
    "source": "likefolio.ai",
    "test": true
  }
}

Errors: 401 · 403-key · 403-tier · 404

GET /v1/webhooks/{webhook_id}/deliveries freequant+Try it →

Latest 50 live and test delivery attempts for this key's webhook, newest first. No credits charged.

Quant+. Only the owning key can read these attempts.

Param	In	Type	Description
`webhook_id` *	path	integer	A webhook owned by this API key.

curlPythonJavaScript

curl -H "X-API-Key: lf_your_key" \
  "https://likefolio.ai/v1/webhooks/12/deliveries"

import requests

r = requests.get(
    "https://likefolio.ai/v1/webhooks/12/deliveries",
    headers={"X-API-Key": "lf_your_key"},
)
r.raise_for_status()
print(r.json(), "|", r.headers.get("X-Credits-Remaining"), "credits left")

const r = await fetch(
  "https://likefolio.ai/v1/webhooks/12/deliveries",
  { headers: { "X-API-Key": "lf_your_key" } });
const data = await r.json();
console.log(data, "|", r.headers.get("X-Credits-Remaining"), "credits left");

Response field	Meaning
`deliveries`	[{kind, event_type, event_count, ok, status_code, error, created_at}]
`count`	Number of attempts returned (at most 50)

Example response

{
  "deliveries": [
    {
      "kind": "test",
      "event_type": "score_move",
      "event_count": 1,
      "ok": true,
      "status_code": 200,
      "error": null,
      "created_at": "2026-09-12 12:00:00"
    }
  ],
  "count": 1
}

Errors: 401 · 403-key · 403-tier · 404