Unusual Whales API: use Python without assuming a client interface
Python can call the Unusual Whales REST API through an HTTP library. A package called a Python client is a separate dependency whose publisher, version and methods must be checked. This guide uses the vendor’s documented HTTP interface; it does not assume that get_option_flow() or get_dark_pool() exists in an official SDK.
Key Takeaways
- Use the official REST operation as the reference for any Python wrapper.
- API, dashboard and commercial data rights are separate checks.
- Validate response meaning and historical availability before interpreting a model result.
Agent access is another supported interface
Unusual Whales also documents a hosted MCP server for compatible AI clients. Its API-key connection and its separate account-login integrations for ChatGPT, Claude and Grok have different authentication requirements. Natural-language access is not exclusive to Pineify. Inspect the operation, returned timestamps and underlying records when evaluating an agent answer.
Start from the vendor request example
The official get-all-flow-alerts notebook uses Python httpx, an environment variable for the token and an Authorization: Bearer header. It requests GET https://api.unusualwhales.com/api/option-trades/flow-alerts. Use that documented operation as the reference when evaluating a wrapper; do not substitute invented convenience methods.
- Store the token outside source code and browser bundles.
- Start with a small permitted query and record the status code and returned schema.
- Keep API credentials out of logs, shared notebooks and exported reports.
Verify a Python wrapper before installing it
Search results contain similarly named Python packages. A familiar product name does not prove vendor maintenance. Follow repository links, review the release history and API documentation, then pin the selected version. Compare its generated request with the current official operation.
- Check synchronous versus asynchronous usage and timeout configuration.
- Confirm whether the return type is parsed JSON, a typed object or a DataFrame; these are not interchangeable.
- Inspect retries and rate-limit handling rather than assuming the library provides them.
Separate API entitlement from dashboard access
Unusual Whales sells API access separately from its website and mobile product, with a combined bundle also listed. Check the current API plan, supported transport, lookback and request limits before purchase. A website subscription price is not evidence of API permission. A free trial is time-limited, not a perpetual free data service.
Preserve data meaning in the pipeline
An alert endpoint may aggregate trades according to alert rules; it is not necessarily the raw tape. Store the operation, parameters, retrieval time and data timestamps with every sample. A blank result can mean no matching observations, a filter mismatch or a request problem; distinguish those cases.
- Handle authentication and entitlement failures separately from rate limits and server errors.
- Use bounded retries only where appropriate; honor the documented limit and any response retry guidance.
- Check pagination, duplicate identifiers, timezone and historical retention for the selected endpoint.
- Do not treat ask-side calls as proven opening buys or use future revisions in an earlier backtest.
Choose an API or a browser research workflow
Use programmatic access when your application needs repeatable retrieval and permitted data storage. For manual investigation, a dashboard can avoid maintaining that pipeline, but it does not return the same callable contract. Pineify Market Insights is an authenticated, plan-gated browser workflow. Pineify also offers agent integrations, which should be evaluated through their own documentation; neither is presented here as a compatible Unusual Whales Python SDK.
Pineify publishes this comparison as a separate product provider. It is based on documentation and the current Pineify implementation, not a live trading or latency benchmark. Market observations and model outputs do not establish participant intent or future returns.