Python sdk

Python SDK

The Python SDK is built for research, ETL, notebooks, and backend services that want REST parity without turning every request into a small framework project.

Start here

1. Install the SDK

   Add the package to the environment where your notebook, worker, or service will run.

2. Set the API key and base URL

   Default to https://api.secapi.ai unless you are testing a local or staging environment.

3. Run one issuer workflow and one semantic investor workflow

   Prove both the investor path and the one-call intelligence path before you move on.

pip install omni-datastream-py

What it is good for

Notebooks

Good for research sessions where you need entity resolution, filings, statements, and compact extracted sections quickly.

Research pipelines

Useful when you need benchmarkable workflows with explicit freshness and provenance metadata.

ETL and enrichment

Fit for downstream enrichment services that need Datastream payloads and artifact workflows.

Backend jobs

Works well in recurring workers that need the same contract shape as the public API.

First useful calls

from omni_datastream_py import OmniDatastreamClient

client = OmniDatastreamClient(
    api_key="ods_test_...",
    base_url="https://api.secapi.ai",
)

issuer = client.resolve_entity(ticker="AAPL")
filing = client.latest_filing(ticker="AAPL", form="10-K")
statements = client.all_statements(ticker="AAPL", period="annual", limit=1)
market = client.market_snapshots(symbols=["AAPL"])
macro = client.macro_indicators(country="JP", indicator_key="CPIAUCSL", limit=3)
factors = client.factor_returns(keys=["MKT_US", "QUALITY"], lookback="6m", window="1m")
answer = client.intelligence_query({
    "query": "Give me a recommendation for how to make this portfolio factor neutral.",
    "portfolio": [
        {"symbol": "AAPL", "weight": 0.4},
        {"symbol": "MSFT", "weight": 0.35},
        {"symbol": "NVDA", "weight": 0.25},
    ],
    "responseMode": "compact_json_and_md",
})

Reliability defaults

The Python SDK retries transient failures with exponential backoff and a per-client circuit breaker.

• Auto-retried by default: GET, HEAD, OPTIONS
• Opt-in required: POST, PUT, PATCH, DELETE, MCP tools/call
• Always retried regardless of method: 429 rate limits, with Retry-After honored

Disable SDK retries when your application already owns retry behavior:

client = OmniDatastreamClient(api_key="ods_test_...", retry=False, telemetry=False)

Opt into mutating retries only when the operation is idempotent:

artifact = client.create_artifact(
    {"kind": "markdown_bundle", "ticker": "AAPL"},
    retry={"enabled": True, "idempotency_key": "artifact-aapl-markdown-bundle"},
)

See SDK reliability for the full retry policy and migration notes.

Dilution intelligence

# Top 10 highest-dilution-risk issuers
ratings = client.dilution_ratings(overall_risk="high", limit=10)

# Single-ticker dilution rollup
score = client.dilution_score(ticker="BBBB")

# ATM offerings only (boolean filter on the events list)
atms = client.dilution_events(ticker="BBBB", is_atm=True)

# Coverage + freshness rollup (no agent shape — already compact)
coverage = client.dilution_coverage(ticker="BBBB")

The full surface — dilution_events, dilution_event_detail, dilution_warrants, dilution_convertibles, dilution_rofr, dilution_lockups, dilution_cash_position, dilution_corporate_actions, dilution_nasdaq_compliance, dilution_ratings, dilution_reverse_splits, dilution_score, dilution_share_float_history, dilution_coverage — mirrors the REST routes 1:1. Add view="agent" to any list call (except dilution_coverage) for the compact agent-mode shape.

CopiedCopy prompt

Operator paths

artifact = client.create_artifact({
    "ticker": "AAPL",
    "form": "10-K",
    "sectionKey": "item_1a",
    "kind": "markdown_bundle",
})
manifest = client.artifact_manifest(artifact["id"])
observability = client.observability()

If you are caching responses in a notebook or long-running worker, keep the freshness block next to the payload. Otherwise you lose the context that tells you whether a result is still safe to trust.

Read next

API Reference

Open the exact wire format behind the Python methods you are using.

Libraries & SDKs

Compare Python with the other runtime surfaces before standardizing.

Benchmark workflows

See how OMNI measures latency, freshness, and workflow parity.