{"id":50727396,"url":"https://github.com/secapi-ai/secapi-python","last_synced_at":"2026-06-10T05:02:32.666Z","repository":{"id":359331527,"uuid":"1245149494","full_name":"secapi-ai/secapi-python","owner":"secapi-ai","description":"Official Python SDK for SEC API","archived":false,"fork":false,"pushed_at":"2026-05-21T00:48:45.000Z","size":16,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-21T19:35:07.889Z","etag":null,"topics":["financial-data","python","sdk","sec-api","sec-edgar"],"latest_commit_sha":null,"homepage":"https://docs.secapi.ai","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/secapi-ai.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-21T00:47:29.000Z","updated_at":"2026-05-21T00:49:00.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/secapi-ai/secapi-python","commit_stats":null,"previous_names":["secapi-ai/secapi-python"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/secapi-ai/secapi-python","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/secapi-ai%2Fsecapi-python","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/secapi-ai%2Fsecapi-python/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/secapi-ai%2Fsecapi-python/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/secapi-ai%2Fsecapi-python/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/secapi-ai","download_url":"https://codeload.github.com/secapi-ai/secapi-python/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/secapi-ai%2Fsecapi-python/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34137570,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-10T02:00:07.152Z","response_time":89,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["financial-data","python","sdk","sec-api","sec-edgar"],"created_at":"2026-06-10T05:02:31.860Z","updated_at":"2026-06-10T05:02:32.657Z","avatar_url":"https://github.com/secapi-ai.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# SEC API Python SDK\n\nPython SDK for [SEC API](https://secapi.ai/developers) -- SEC filings, financial statements, ownership data, and more.\n\n## Installation\n\n```bash\npip install secapi-client\n```\n\n## Configuration\n\n```python\nfrom secapi_client import SecApiClient\n\nclient = SecApiClient(\n    api_key=\"ods_test_...\",\n    # Optional: override base URL (defaults to https://api.secapi.ai)\n    # base_url=\"http://127.0.0.1:8787\",\n)\n```\n\nYou can also authenticate with a Bearer token:\n\n```python\nclient = SecApiClient(bearer_token=\"your-bearer-token\")\n```\n\n`omni_datastream_py`, `OmniDatastreamClient`, and `OmniDatastreamError` remain available for existing integrations.\n\n### Environment Variables\n\n| Variable | Description |\n|----------|-------------|\n| `SECAPI_API_KEY` | Your SEC API key (starts with `ods_`) |\n| `OMNI_DATASTREAM_API_KEY` | Legacy fallback for existing integrations |\n\n### Configuration Options\n\n| Parameter | Default | Description |\n|-----------|---------|-------------|\n| `api_key` | `None` | API key authentication |\n| `bearer_token` | `None` | Bearer token authentication |\n| `base_url` | `https://api.secapi.ai` | API base URL |\n| `api_version` | `2026-03-19` | API version header |\n| `retry` | `None` | Retry configuration, or `False` to disable SDK retries |\n| `telemetry` | `None` | Retry telemetry configuration, or `False` to opt out |\n\n## Reliability\n\nThe SDK retries transient failures with exponential backoff and jitter. Defaults:\n\n- Auto-retried by default: `GET`, `HEAD`, `OPTIONS`\n- Opt-in required: `POST`, `PUT`, `PATCH`, `DELETE`, MCP `tools/call`\n- Always retried regardless of method: `429` rate limits, with `Retry-After` honored\n- Retryable failures: network errors, `408`, `429`, `502`, `503`, `504`\n- Never retried: `400`, `401`, `403`, `404`, `422`\n- Backoff: base `200ms`, max `5s`, max retries `3`, total budget `30s`\n- Circuit breaker: opens after 5 consecutive retryable failures, cools down for 60s\n\nDisable retries globally if you already wrap the SDK with your own retry layer:\n\n```python\nclient = SecApiClient(\n    api_key=\"ods_test_...\",\n    retry=False,\n)\n```\n\nPer-call overrides are supported:\n\n```python\nfiling = client.latest_filing(ticker=\"AAPL\", form=\"10-K\", retry=False)\n\nartifact = client.create_artifact(\n    {\"kind\": \"audit\", \"payload\": {\"ticker\": \"AAPL\"}},\n    retry={\"enabled\": True, \"idempotency_key\": \"artifact-aapl-audit-2026-05-01\"},\n)\n```\n\nOnly opt into retries for mutating requests when the operation is idempotent from your application's point of view. Provide an idempotency key so ambiguous network failures can be correlated safely.\n\nRetry telemetry emits anonymous `client_retry_attempt` events to SEC API's telemetry project. Set `telemetry=False` globally or per call to opt out.\n\n## Quickstart\n\n```python\nimport os\nfrom secapi_client import SecApiClient\n\napi_key = os.environ.get(\"SECAPI_API_KEY\") or os.environ[\"OMNI_DATASTREAM_API_KEY\"]\nclient = SecApiClient(api_key=api_key)\n\n# Resolve a company entity\nentity = client.resolve_entity(ticker=\"AAPL\")\nprint(entity)\n\n# Get the latest 10-K filing\nfiling = client.latest_filing(ticker=\"AAPL\", form=\"10-K\")\nprint(filing)\n\n# Extract a specific section\nsection = client.latest_section(\n    section_key=\"item_1a\",\n    ticker=\"AAPL\",\n    form=\"10-K\",\n    mode=\"compact\",\n)\nprint(section)\n```\n\n## Common Use Cases\n\n### Financial Statements\n\n```python\n# XBRL facts\nfacts = client.facts(ticker=\"AAPL\", tag=\"Assets\", taxonomy=\"us-gaap\", limit=5)\n\n# Full financial statements\nstatements = client.all_statements(ticker=\"AAPL\", period=\"annual\", limit=3)\n```\n\n### Ownership and Institutional Holdings\n\n```python\n# Latest 13F filing (institutional holdings)\nholdings = client.latest_13f(cik=\"0001067983\", limit=10)\n```\n\n### Market Data\n\n```python\n# Market calendar\ncalendar = client.market_calendar(market=\"XNYS\", duration=3)\n\n# Volatility signal\nvol = client.volatility_signal(ticker=\"AAPL\")\n```\n\n### Offerings and M\u0026A\n\n```python\n# IPO and offering filings\nofferings = client.offerings(forms=\"S-1,424B4\", limit=3)\n```\n\n### Diagnostics\n\n```python\n# Artifact summary (data freshness)\nsummary = client.artifact_summary()\n\n# System observability (requires admin:operator)\noperator_client = SecApiClient(api_key=os.environ[\"OMNI_OPERATOR_API_KEY\"])\nobs = operator_client.observability()\n```\n\n## Error Handling\n\n```python\nfrom secapi_client import SecApiClient, SecApiError\n\nclient = SecApiClient(api_key=\"ods_test_...\")\n\ntry:\n    result = client.resolve_entity(ticker=\"INVALID\")\nexcept SecApiError as e:\n    print(f\"Status: {e.status}\")\n    print(f\"Payload: {e.payload}\")\n```\n\n## Scope\n\nThe Python SDK covers the full REST surface including:\n\n- Entity resolution and search\n- Filing retrieval and section extraction\n- XBRL facts and financial statements\n- Offerings, market calendar, and volatility signals\n- Ownership, insiders, and compensation data\n- Institutional holdings (13F)\n- Enforcement actions and M\u0026A events\n- Artifacts, diagnostics, and observability\n- Events, streams, and webhooks\n\n## MCP (Model Context Protocol)\n\nMCP tool calls use HTTP `POST`, so they are not retried on `502`/`503` by default. Opt in per call only when the tool is read-only or otherwise idempotent:\n\n```python\nresult = client.mcp(\n    {\n        \"jsonrpc\": \"2.0\",\n        \"id\": \"1\",\n        \"method\": \"tools/call\",\n        \"params\": {\"name\": \"entities.resolve\", \"arguments\": {\"ticker\": \"AAPL\"}},\n    },\n    retry={\"enabled\": True, \"idempotency_key\": \"mcp-entities-resolve-aapl\"},\n)\n```\n\n## Links\n\n- [API Documentation](https://docs.secapi.ai)\n- [Developer Portal](https://secapi.ai/developers)\n- [GitHub Repository](https://github.com/autonomous-computer/omni-datastream)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsecapi-ai%2Fsecapi-python","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsecapi-ai%2Fsecapi-python","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsecapi-ai%2Fsecapi-python/lists"}