profitelligence

SEC filings, insider trading and market signals in Python.

pip install profitelligence

import profitelligence as prof

prof.api_key("pk_live_...")  # or set PROFITELLIGENCE_API_KEY
prices = prof.company.ohlc("AAPL", days=90)  # 90 rows, typed
prices[0].close  # 305.69, a float
prices.df  # a DataFrame, with [pandas]

That is the whole idea. The Profitelligence API answers in pipe-delimited CSV. This package parses it, types it, and hands you rows you can work with.

What you get

Nine namespaces cover 68 endpoints. Every method is generated from the same API reference the documentation site renders, so the package cannot describe an endpoint the API does not have.

Every method carries the endpoint's own documentation. In a notebook, prof.form4.clusters? shows the arguments, the tier it needs, and the columns it returns.

Authentication

Get a key at profitelligence.com/account/api-keys.

prof.api_key("pk_live_...")  # for a notebook

export PROFITELLIGENCE_API_KEY=pk_live_...

You can also call with no key at all. Guests reach the free endpoints on the top 500 symbols, which is enough to try the package before you sign up.

In a service, build a client and hold it. One client is one connection pool.

from profitelligence import Client

with Client(api_key="pk_live_...", timeout=60) as prof:
    holdings = prof.institutional.manager_top_holdings("0001067983")

Tables

CSV endpoints return a Table: named columns, typed values, one row object per record. It is a normal Python sequence, so index it, slice it, and iterate it.

prices = prof.company.ohlc("AAPL,MSFT", days=180)

prices.columns  # ['symbol', 'time', 'open', 'high', 'low', 'close']
len(prices)  # 360
prices[0].close  # 305.69            a float
prices[0].time  # date(2026, 8, 17) a date
prices.column("close")  # the whole column
prices.to_dicts()  # plain dictionaries

Types come from the API reference where it declares them, and from the data where it does not. A column is typed as a whole: if one value will not parse, the column stays text rather than becoming a mix you cannot do arithmetic on. An empty cell is None, never 0 and never "".

For pandas, install the extra:

pip install 'profitelligence[pandas]'

frame = prices.df  # or prices.to_pandas()
frame.set_index("time").close.resample("W").last()

Date columns arrive as datetime64, so resampling and plotting work with no further conversion.

JSON endpoints — the page routes, FRED, search, and the knowledge graph — return the decoded body as it stands.

When a call does not work

Errors say what happened, in the API's own words.

try:
    scores = prof.analytics.opportunities()
except prof.UpgradeRequired as error:
    print(error.message)  # the plan this endpoint needs
except prof.RateLimited as error:
    print(error.retry_after)  # seconds until the window resets

All of them inherit ProfitelligenceError.

A rate limit is never retried behind your back. A notebook that sleeps for a minute without telling you is worse than an error you can see. Server errors and timeouts are retried twice, with backoff.

Two of these deserve a word. The API sometimes reports a problem in-band: HTTP 200, with a body of error,<message>. Read raw, that looks like success and parses to nothing. This package raises instead — BadRequest when you caused it, NoData when the API simply had nothing — so an empty result never passes for a real one. A genuinely empty result, which the API returns as a header row with no data rows, stays an empty Table.

What this package does not do

It reads. There is nothing here that writes to your account, and nothing that places a trade.

It reports what filings and prices show. It does not advise, predict, or recommend. What you do with the data is your decision, and a licensed advisor is the right person to help you make it.

Rate limits and tiers

Each key has a request window and a symbol list that follow your plan. Guests and Free see the top 500 symbols, Pro the top 6,000, Elite all of them. A symbol outside your tier raises UpgradeRequired with the plan it needs.

How this package is built

The client is generated. The nine modules under src/profitelligence/resources/ are produced by codegen/generate.py from codegen/spec.json, which is exported from the same API reference that renders at profitelligence.com/api-reference. That reference is the contract: an endpoint reaches this package by being documented, not by someone hand-writing a signature.

Editing a generated file therefore has no lasting effect — the next generation replaces it. The hand-written part is the core: client.py, _http.py, table.py and errors.py.

uv sync --group dev
pytest                  # offline, every response mocked
pytest -m live          # hits the public API; no key needed for the free endpoints
ruff check . && ruff format --check .

Development happens in a private repository and is pushed here in one direction, so a pull request cannot be merged into this tree. Bug reports are genuinely useful and are acted on — see CONTRIBUTING.md for what helps most.

License

MIT. See LICENSE.