Skip to main content

​
Monitors

Monitors are saved searches that trigger delivery to a destination — either a webhook or an email address — when new SEC filings match the query. Use monitors for inbox-grade alerting on portfolio events: 8-K material events, 13F holdings changes, insider transactions, AAERs, auditor changes, and any keyword search the filing search supports.

​
Lifecycle

  1. Create a monitor with POST /v1/monitors. Provide name, query, and optionally filters (e.g., { ticker, form, date_from, date_to }) plus a delivery destination (webhook or email).
  2. Inspect recent matches on demand with GET /v1/monitors/{monitor_id}/matches.
  3. List your org’s monitors with GET /v1/monitors.
  4. Deactivate a monitor with DELETE /v1/monitors/{monitor_id} (idempotent; sets is_active=false).
  5. Replace the delivery destination on an existing monitor with POST /v1/monitors/{monitor_id}/delivery.

​
Destination types

A monitor has exactly one delivery destination in v1. To send the same query to multiple channels, create one monitor per channel.

​
Webhook (legacy single-URL path)

The webhookUrl field on a monitor sends matches to a signed webhook endpoint. Webhook delivery uses the same signing protocol as POST /v1/webhook_endpoints — see Webhook and stream workflows for the full lifecycle and signature verification details. 
curl -X POST https://api.secapi.ai/v1/monitors \
  -H "Authorization: Bearer $SECAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Goodwill impairments",
    "query": "goodwill impairment",
    "filters": { "form": "8-K" },
    "webhookUrl": "https://your-app.example.com/hooks/sec-api"
  }'

​
Email

Email delivery uses Resend as the transactional provider. Each match-batch produces a single email containing the rendered HTML + plaintext alongside an RFC 8058-compliant List-Unsubscribe header for one-click client integrations. The delivery object in the request body is a discriminated union; future channels (Slack, etc.) extend the type field. 
curl -X POST https://api.secapi.ai/v1/monitors \
  -H "Authorization: Bearer $SECAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Goodwill impairments",
    "query": "goodwill impairment",
    "filters": { "form": "8-K" },
    "delivery": {
      "type": "email",
      "config": { "to": "alerts@your-firm.com" }
    }
  }'
The response includes a delivery block describing the destination: 
{
  "object": "monitor",
  "id": "mon_...",
  "delivery": {
    "type": "email",
    "config": { "to": "alerts@your-firm.com" },
    "status": "active"
  },
  ...
}
delivery.status cycles through active → unsubscribed (one-click from email) or bounced (set by future bounce-webhook handling). When status is anything other than active, the email channel does not fire.

​
Email behavior

Every email includes a signed unsubscribe link in the body and the List-Unsubscribe header. Modern mail clients can use one-click unsubscribe, and recipients can re-enable delivery by updating the monitor destination. SEC API retries transient email failures with exponential backoff and exposes delivery state through monitor and webhook delivery APIs. Worst-case latency from filing publication to email arrival is approximately 7.5 minutes.

​
Daily summary

For each org that hits the rate limit on any monitor in a 24-hour window, SEC API sends one rolled-up summary email per (org, recipient) at 23:55 UTC. The summary lists every monitor that hit the cap with the total match count for the day; the body is plain text + HTML, both Outlook-safe. The summary is idempotent per (org, recipient, UTC date) — re-running the daily-summary asset on the same UTC date is a no-op. Customers who’d like to disable the summary entirely can unsubscribe via the List-Unsubscribe header on any monitor email, which flips delivery.status to unsubscribed (the dispatcher then skips that monitor entirely until the customer re-enables via POST /v1/monitors/{monitor_id}/delivery).

​
Limits

  • Search modes: only keyword is supported in monitor execution at this time. Semantic search support will land in a future release.
  • One destination per monitor: v1 supports a single delivery destination per monitor row. Use multiple monitors to fan out to multiple channels for now.
  • Quota: email delivery is metered as email_delivery (180 sends per minute by default per org). Adjust via the standard plan policy override env.
  • Legacy webhookUrl: new monitors should use delivery.type='email' or subscribe an organization-level webhook endpoint to the monitor.match event type.