Skip to main content

​
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

Install the public Python package.
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 secapi-client
The SDK mirrors the same endpoints and x-api-key authentication as the REST examples below.

​
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 SEC API payloads and artifact workflows.

Backend jobs

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

​
First useful calls with REST

import os
import requests

BASE_URL = "https://api.secapi.ai"
HEADERS = {"x-api-key": os.environ["SECAPI_API_KEY"]}

def get_json(path, params=None):
    response = requests.get(f"{BASE_URL}{path}", params=params, headers=HEADERS, timeout=30)
    response.raise_for_status()
    return response.json()

issuer = get_json("/v1/entities/resolve", {"ticker": "AAPL"})
filing = get_json("/v1/filings/latest", {"ticker": "AAPL", "form": "10-K"})
statements = get_json("/v1/statements/all", {"ticker": "AAPL", "period": "annual", "limit": 1})
market = get_json("/v1/market/snapshots", {"symbols": "AAPL"})

answer_response = requests.post(
    f"{BASE_URL}/v1/intelligence/query",
    headers={**HEADERS, "Content-Type": "application/json"},
    json={
        "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",
    },
    timeout=60,
)
answer_response.raise_for_status()
answer = answer_response.json()

​
SDK shape

The public Python package name is secapi-client: 
import os
from secapi_client import SecApiClient

client = SecApiClient(api_key=os.environ["SECAPI_API_KEY"])
filing = client.latest_filing(ticker="AAPL", form="10-K")

​
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 = SecApiClient(api_key=os.environ["SECAPI_API_KEY"], 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 API — 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.

Copy this SEC API prompt for your agent.

​
Artifact paths

artifact = client.create_artifact({
    "ticker": "AAPL",
    "form": "10-K",
    "sectionKey": "item_1a",
    "kind": "markdown_bundle",
})
manifest = client.artifact_manifest(artifact["id"])
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.

API Reference

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

Libraries & SDKs

Compare Python with the other runtime options before standardizing.

Benchmark workflows

See how SEC API measures latency, freshness, and workflow parity.