Special Situations Workflows

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.

Special Situations is a paid public API with a limited free website preview. The free public Situations database is for discovery and manual research. An API key on a paid organization plan enables programmatic search, exports, archive reads, and monitoring.

Choose the right object

Need	Start with	Why
Scan live candidates	`GET /v1/situations`	A current, filterable roster of durable situations
Explain a current candidate	`GET /v1/situations/{situation_id}`	Current terms, narrative, market context, and filing timeline
Cite a concise agent brief	`GET /v1/situations/{situation_id}/export`	Source-cited Markdown designed for downstream models
Build a single research packet	`GET /v1/situations/{situation_id}/underwriting-pack`	Canonical detail, narrative, timeline, and Copy-for-LLM Markdown together
Reproduce a past digest	`GET /v1/situations/issues/{issue}`	Immutable publication-time snapshot, not live data
React to a material update	`POST /v1/situations/watchlists`	Durable monitoring with explicit filters, 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
curl --fail-with-body -H "x-api-key: $SECAPI_API_KEY" \
  "https://api.secapi.ai/v1/situations/sit_abc123/export" > 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. The API-key example below creates a filter-only watch with delivery suppressed; activate email or organization fanout only from a bearer-authenticated workflow after signed webhook or stream delivery has been configured and tested.

curl --fail-with-body -X POST \
  -H "x-api-key: $SECAPI_API_KEY" \
  -H "content-type: application/json" \
  "https://api.secapi.ai/v1/situations/watchlists" \
  -d '{
    "name": "ACME vote and close monitoring",
    "query": "sit_abc123",
    "searchMode": "situation",
    "filters": { "situationIds": ["sit_abc123"] }
  }'

Watchlist create, read, and update operations report monitor_management. Delivery activation may require an additional delivery entitlement and delivery-specific metering. 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

Use hosted MCP discovery as the source of truth for available tools. The published workflow supports discovery/list, detail, feed, calendar, stats, and performance tools when advertised; use REST for export, archive, underwriting, and watchlist operations until discovery advertises equivalent tools. 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 inspect the deployed tool list before issuing durable research or monitoring operations. 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 intentionally covers only the public Special Situations API workflow: discovery, cited research, and monitoring.

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. For route-specific reads, preserve the SECAPI-Meter-Class response header rather than hard-coding meter assumptions. Special Situations provides SEC-derived situation and filing data; it does not provide proprietary enrichment or investment advice.

Delivery & audit

Special Situations Workflows

Choose the right object

1. Discover, then narrow

2. Build a source-cited research packet

3. Use immutable issues for reproducibility

4. Monitor after you have a thesis

MCP and reusable Skills

Cost and entitlement posture

Read next

​Choose the right object

​1. Discover, then narrow

​2. Build a source-cited research packet

​3. Use immutable issues for reproducibility

​4. Monitor after you have a thesis

​MCP and reusable Skills

​Cost and entitlement posture

​Read next

Choose the right object

1. Discover, then narrow

2. Build a source-cited research packet

3. Use immutable issues for reproducibility

4. Monitor after you have a thesis

MCP and reusable Skills

Cost and entitlement posture

Read next