Skip to main content
Use Special Situations as a durable SEC-derived research layer: discover a live population, open the cited event trail behind a candidate, preserve a fixed weekly archive when reproducibility matters, and monitor only the set that actually warrants attention.
This is a paid public API product. The free Situations database is useful for discovery and organic research; API keys unlock programmatic search, exports, archive reads, and monitoring under your organization plan.

​
Choose the right object

NeedStart withWhy
Scan live candidatesGET /v1/situationsA current, filterable roster of durable situations
Explain a current candidateGET /v1/situations/{situation_id}Current terms, narrative, market context, and filing timeline
Cite a concise agent briefGET /v1/situations/{situation_id}/exportSource-cited Markdown designed for downstream models
Build a single research packetGET /v1/situations/{situation_id}/underwriting-packCanonical detail, narrative, timeline, and Copy-for-LLM Markdown together
Reproduce a past digestGET /v1/situations/issues/{issue}Immutable publication-time snapshot, not live data
React to a material updatesecapi situations watchDurable delivery with an explicit destination and provenance

​
1. Discover, then narrow

Use the lean projection for a broad roster. It lowers transport and parsing cost; it does not lower the meter for the request. 
secapi situations list \
  --types merger,tender_offer \
  --statuses announced,pending \
  --enrich false \
  --limit 100
When the investigation begins with a filing type rather than a company, let the server expand the EDGAR form to the situations it can trigger: 
secapi situations by-form --form "SC 13D" --limit 25
secapi situations calendar --date-types vote,expected_close --days 30

​
2. Build a source-cited research packet

Retrieve current detail before asking an agent to interpret a situation. Keep the situationId, accession numbers, source URLs, event dates, requestId, and traceparent with the resulting memo. An export is a factual brief, not investment advice and not a substitute for source-filing review. 
secapi situations get --situation-id sit_abc123
secapi situations export --situation-id sit_abc123 > situation-brief.md

​
3. Use immutable issues for reproducibility

Issue data answers a historical question: what did the digest publish then? Live detail answers a current question: what does the situation look like now? Keep those two facts separate in stored research. 
curl -H "x-api-key: $SECAPI_API_KEY" \
  "https://api.secapi.ai/v1/situations/issues?limit=12"

curl -H "x-api-key: $SECAPI_API_KEY" \
  "https://api.secapi.ai/v1/situations/issues/42"
The issue number or slug, publication timestamp, sourceSituationIds, sourceEventIds, and source-event snapshots are the reproducibility anchors. Fetch the referenced situationId separately before describing live terms or current status.

​
4. Monitor after you have a thesis

Create a monitor only after narrowing the universe. A direct email monitor is appropriate for a person; organization fanout is appropriate only after signed webhook or stream delivery has been configured and tested. 
secapi situations watch \
  --situation-ids sit_abc123 \
  --use-org-webhooks \
  --name "ACME vote and close monitoring"
Creating, reading, or changing a watch reports the monitor_management control-plane meter. A successful direct-email delivery reports email_delivery; successful organization-level webhook or stream fanout reports situations_webhook_delivery. Preserve delivery IDs and source filing provenance, verify inbound signatures over the raw body, and replay only failed deliveries when the receiving system is ready.

​
MCP and reusable Skills

The hosted MCP surface currently exposes situations.list, situations.get, situations.feed, situations.calendar, situations.stats, situations.performance, situations.export, and situations.watch. Tool calls use the same organization key, entitlement checks, meter classes, and source-citation expectations as REST. Install the server with the MCP setup guide, then let an agent use the discovery tools before issuing a durable watch. The bundled track-special-situations Skill is the CLI-oriented counterpart: it guides an agent from a broad roster to live detail, a cited export, and an intentional monitor. It does not expose the internal Omni Apps market or fundamentals layer.

​
Cost and entitlement posture

Before a batch or an agent loop, retrieve GET /v1/limits and GET /v1/billing/rates. For every request, log the response meter and billing headers rather than hard-coding a plan assumption. The important Special Situations meter classes are situations_lookup, situations_feed_read, situations_export, situations_underwriting_pack, monitor_management, email_delivery, and situations_webhook_delivery. The TIKR-style fundamentals, estimates, valuation, and broad international symbol dataset used by Omni Apps are internal-only infrastructure. They are not part of this public Special Situations API, documentation, SDK, CLI, MCP, or pricing promise.