fAlpha Account API
The Account API from fAlpha — 2 operation(s) for account.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/falpha-ai:falpha-ai-account-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.0
info:
title: fAlpha.ai Account API
description: 'Welcome to the fAlpha.ai API. Access trading signals, daily sentiment scores, and scraped news articles for S&P 500 tickers and beyond. API access is currently available to enterprise users only. Please contact info@bam.money to request access. By using the API, you consent to the Terms of Service and Privacy Policy. ## Interactive Docs Guidance
Use `/docs` for quick, small validation requests. For larger batched queries or longer date ranges, prefer the generated `curl` command or call the endpoint URL directly from your browser or API client. Large JSON responses can make the interactive Swagger UI sluggish even when the API itself is healthy. Current date-range and size caps are:
- `GET /signals-history/{ticker}`: up to **365 days**
- `GET /signals-history-batched`: up to **90 days**
- `GET /signals-history-all`: up to **30 days**
- `GET /signals-batched`: up to **100 tickers** per call (latest signal per ticker)
- `GET /screener`: up to **50 rows** per call
After a large test, click **Clear** for that operation or refresh the page to keep the interactive docs responsive. ## Data Dictionary
The API currently returns the following response fields:
| Field | Meaning |
| --- | --- |
| `ticker` | Security ticker symbol, for example `AAPL`. |
| `date` | For signals: the model run date in UTC. For articles: the crawl date in UTC. |
| `period` | Signal forecast horizon. Current supported values are `5d`, `15d`, and `2m`. |
| `regime` | Market regime used for the signal model: `neutral`, `bear`, or `bull`. |
| `signal` | Trading direction returned by the model: `buy` or `sell`. |
| `confidence` | Absolute value of the signal score used to rank signal strength. Recent rows use the index-adjusted score; older historical rows may fall back to the raw score when adjusted data is unavailable. |
| `sentiment` | News sentiment paired with the signal: the **previous calendar day''s** finalized average score (news is crawled overnight — including weekends — so day D''s sentiment isn''t ready when the day-D signal is produced; the most recent finalized reading is D-1''s). Returns `null` when that reading is unavailable (internally, a stored score of `10.0` is a "not computed" sentinel and is always surfaced as `null`). |
| `quality` | Optional block of signal quality metrics. `null` unless the request sets `include_quality=true`; individual metrics may still be `null` when unavailable for a row. |
| `quality.sharpe_ratio` | Risk-adjusted measure of the signal''s recent strength (a Sharpe-ratio proxy). Higher is better; can be negative. |
| `quality.sortino_ratio` | Downside-risk-adjusted counterpart to the Sharpe ratio. |
| `quality.iis_score` | Information-strength score for the signal at this horizon. |
| `quality.normalized_iis` | IIS score normalized for cross-ticker comparison. |
| `quality.percent_positive_pnl` | Percentage of recent signal-following outcomes with positive PnL (0–100). |
| `performance` | Optional realized-performance block on history rows. `null` unless the request sets `include_performance=true`. Values are backfilled once returns are realized, so recent rows return `null` fields. |
| `performance.pnl` | Realized signal-following PnL for the row''s horizon. |
| `performance.ticker_return` / `performance.index_return` | Realized gross-return ratios over the horizon for the ticker and the benchmark index (`1.05` = +5%). |
| `performance.release_date` | When realized returns were backfilled for the row. |
| `as_of` | Screener responses: the model-run date of the screened signal cube (the latest available). |
| `surface` | Usage metering: originating client surface — `excel`, `sheets`, `sdk-python`, `zapier`, or `api` (default) — attributed via the optional `X-Falpha-Surface` request header. |
| `by_client` | Usage metering: split by anonymous install id (optional `X-Falpha-Client` header; each add-in install / spreadsheet generates its own). No user accounts involved.'
termsOfService: https://bam.money/terms
contact:
name: fAlpha.ai
url: https://bam.money/contact
email: info@bam.money
version: 0.2.0
servers:
- url: https://api.falpha.ai
description: fAlpha.ai API server
tags:
- name: Account
paths:
/account:
get:
tags:
- Account
summary: Account
description: Returns the account and role information associated with the provided API key. Any valid API key can call this endpoint, even without enterprise access, so customers can inspect why they are (or are not) being granted access.
operationId: get_account_account_get
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/account_response'
security:
- APIKeyQuery: []
- APIKeyHeader: []
/account/usage:
get:
tags:
- Account
summary: Account Usage
description: 'Aggregated API usage for the calling key over the last N days (default 30): totals by day, by endpoint, and by client surface (excel / sdk-python / api). Surfaces are attributed via the optional X-Falpha-Surface request header. Available to any valid API key. Counts successful and failed requests (failures are recorded by the metering middleware with their status_code).'
operationId: get_account_usage_account_usage_get
security:
- APIKeyQuery: []
- APIKeyHeader: []
parameters:
- name: days
in: query
required: false
schema:
type: integer
maximum: 90
minimum: 1
description: Aggregation window in days (max 90)
default: 30
title: Days
description: Aggregation window in days (max 90)
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/usage_response'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
components:
schemas:
account_response:
properties:
email:
anyOf:
- type: string
- type: 'null'
title: Email
is_admin:
type: boolean
title: Is Admin
default: false
is_enterprise:
type: boolean
title: Is Enterprise
default: false
api_disabled:
type: boolean
title: Api Disabled
default: false
role:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Role
billing:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Billing
type: object
title: account_response
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
msg:
type: string
title: Message
type:
type: string
title: Error Type
type: object
required:
- loc
- msg
- type
title: ValidationError
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
usage_bucket:
properties:
key:
type: string
title: Key
description: 'Bucket label: a YYYY-MM-DD day, an endpoint path, or a surface name'
count:
type: integer
title: Count
type: object
required:
- key
- count
title: usage_bucket
usage_response:
properties:
window_days:
type: integer
title: Window Days
description: Size of the aggregation window in days
since:
type: string
format: date-time
title: Since
description: UTC start of the aggregation window
total:
type: integer
title: Total
description: Total successful requests recorded in the window
by_day:
items:
$ref: '#/components/schemas/usage_bucket'
type: array
title: By Day
by_endpoint:
items:
$ref: '#/components/schemas/usage_bucket'
type: array
title: By Endpoint
by_surface:
items:
$ref: '#/components/schemas/usage_bucket'
type: array
title: By Surface
description: 'Split by client surface: excel, sheets, sdk-python, zapier, or api (default)'
by_client:
items:
$ref: '#/components/schemas/usage_bucket'
type: array
title: By Client
description: Split by anonymous install id (X-Falpha-Client header); requests without one bucket under '-'
meter:
additionalProperties: true
type: object
title: Meter
description: 'Unified work meter summed over the window: db_calls, db_docs, db_ms (see dbmeter contract). Requests are traffic; the meter is work.'
type: object
required:
- window_days
- since
- total
- by_day
- by_endpoint
- by_surface
title: usage_response
securitySchemes:
APIKeyQuery:
type: apiKey
in: query
name: api_key
APIKeyHeader:
type: apiKey
in: header
name: X-API-Key
x-topics:
- title: Getting Started
content: '
To get started, contact the fAlpha.ai team to provision enterprise API access and an API key.
1. Contact [info@bam.money](mailto:info@bam.money)
2. Receive your enterprise API credentials
3. Use your API key to access the API
'
- title: Authentication
content: '
The fAlpha.ai API uses API keys to authenticate requests. Send your key in the `X-API-Key` request header (preferred):
```
curl -H "X-API-Key: YOUR_KEY" https://api.falpha.ai/signals/NVDA
```
The legacy `api_key` query parameter is still accepted for backward compatibility. Prefer the header: query strings tend to be captured in proxy/server logs and browser history. When both are sent, the header wins.
> info
> Your API keys carry many privileges, so be sure to keep them secure! **Do not share your API keys** in publicly accessible areas such as GitHub, client-side code, and so forth.
'
- title: Rate Limits
content: '
The fAlpha.ai API enforces rate limits per API key:
- **10 requests per second** (burst cap)
- **300 requests per minute** (sustained cap)
If you exceed either limit, you will receive a `429 Too Many Requests` response with a `Retry-After` header indicating how many seconds to wait before retrying.
The official Python SDK and Excel add-in pace themselves within these limits automatically (client-side token buckets, request batching, and `Retry-After`-aware retries), so a 100-ticker watchlist still resolves in a single request via `GET /signals-batched`.
'
- title: Client Surfaces (SDK & Excel)
content: '
Three first-party client surfaces wrap this API:
- **Python SDK (`falpha`)** — a typed client with client-side rate limiting, retries, pandas integration, analytics helpers (screener, signal flips, regime consensus, pre-trade validation), and a CLI.
- **Excel add-in** — `=FALPHA.*` custom functions (single cells, spilled history, watchlists, screener) plus a task pane with account, usage, and pre-trade validation panels.
- **Google Sheets add-on** — `FALPHA_*` custom functions and a sidebar with the same watchlist / validator / screener / usage workflows.
Each sends an `X-Falpha-Surface` header (`sdk-python` / `excel` / `sheets`) so `GET /account/usage` can meter usage per surface. Direct integrations may omit the header (metered as `api`).
'
- title: Interactive Docs Guidance
content: '
## Interactive Docs Guidance
Use `/docs` for quick, small validation requests.
For larger batched queries or longer date ranges, prefer the generated `curl` command or call the endpoint URL directly from your browser or API client. Large JSON responses can make the interactive Swagger UI sluggish even when the API itself is healthy.
Current date-range and size caps are:
- `GET /signals-history/{ticker}`: up to **365 days**
- `GET /signals-history-batched`: up to **90 days**
- `GET /signals-history-all`: up to **30 days**
- `GET /signals-batched`: up to **100 tickers** per call (latest signal per ticker)
- `GET /screener`: up to **50 rows** per call
After a large test, click **Clear** for that operation or refresh the page to keep the interactive docs responsive.
'
- title: Enterprise Access
content: '
The API is currently available to enterprise users only. To access data (including sentiment scores and summaries) for our full corpus of 16,000+ tickers, please contact [info@falpha.ai](mailto:info@falpha.ai).
'
- title: Data Timing
content: '
- **Signal dates** reflect the model run date (UTC). A signal dated 2026-04-14 uses market data available as of that date; prices in the signal correspond to the previous trading day''s close.
- **Sentiment scores** and **articles** correspond to the crawl calendar day (UTC midnight). The crawl runs overnight (including weekends), so a signal''s paired `sentiment` is the **previous calendar day''s** finalized score, not the signal date''s. Up to 10 articles per ticker per day are scraped.
- **Realized performance fields** (`include_performance=true`) are backfilled after each horizon completes, so the most recent history rows return `null` values until returns are realized.
- All timestamps in API responses are in UTC.
'
- title: Data Dictionary
content: '
## Data Dictionary
The API currently returns the following response fields:
| Field | Meaning |
| --- | --- |
| `ticker` | Security ticker symbol, for example `AAPL`. |
| `date` | For signals: the model run date in UTC. For articles: the crawl date in UTC. |
| `period` | Signal forecast horizon. Current supported values are `5d`, `15d`, and `2m`. |
| `regime` | Market regime used for the signal model: `neutral`, `bear`, or `bull`. |
| `signal` | Trading direction returned by the model: `buy` or `sell`. |
| `confidence` | Absolute value of the signal score used to rank signal strength. Recent rows use the index-adjusted score; older historical rows may fall back to the raw score when adjusted data is unavailable. |
| `sentiment` | News sentiment paired with the signal: the **previous calendar day''s** finalized average score (news is crawled overnight — including weekends — so day D''s sentiment isn''t ready when the day-D signal is produced; the most recent finalized reading is D-1''s). Returns `null` when that reading is unavailable (internally, a stored score of `10.0` is a "not computed" sentinel and is always surfaced as `null`). |
| `quality` | Optional block of signal quality metrics. `null` unless the request sets `include_quality=true`; individual metrics may still be `null` when unavailable for a row. |
| `quality.sharpe_ratio` | Risk-adjusted measure of the signal''s recent strength (a Sharpe-ratio proxy). Higher is better; can be negative. |
| `quality.sortino_ratio` | Downside-risk-adjusted counterpart to the Sharpe ratio. |
| `quality.iis_score` | Information-strength score for the signal at this horizon. |
| `quality.normalized_iis` | IIS score normalized for cross-ticker comparison. |
| `quality.percent_positive_pnl` | Percentage of recent signal-following outcomes with positive PnL (0–100). |
| `performance` | Optional realized-performance block on history rows. `null` unless the request sets `include_performance=true`. Values are backfilled once returns are realized, so recent rows return `null` fields. |
| `performance.pnl` | Realized signal-following PnL for the row''s horizon. |
| `performance.ticker_return` / `performance.index_return` | Realized gross-return ratios over the horizon for the ticker and the benchmark index (`1.05` = +5%). |
| `performance.release_date` | When realized returns were backfilled for the row. |
| `as_of` | Screener responses: the model-run date of the screened signal cube (the latest available). |
| `surface` | Usage metering: originating client surface — `excel`, `sheets`, `sdk-python`, `zapier`, or `api` (default) — attributed via the optional `X-Falpha-Surface` request header. |
| `by_client` | Usage metering: split by anonymous install id (optional `X-Falpha-Client` header; each add-in install / spreadsheet generates its own). No user accounts involved. |
| `predictions` | Historical array of signal rows for a ticker. |
| `count` | Number of articles returned in an articles response. |
| `articles` | Array of article objects returned by the articles endpoint. |
| `title` | Article headline. |
| `score` | Sentiment score for an individual article. |
| `source` | Source domain or publisher for the article. |
| `summary` | AI-generated summary for the article when available. |
| `link` | Canonical article URL. |
| `account` | Role, access, and subscription metadata for the caller. Returned by `GET /account` and available to any authenticated API key, including non-enterprise ones. |
'