Skip to main content
You need a support-friendly way to inspect request, webhook, and stream event history outside the live API response path. SEC API supports filtered delivery-ledger listing and JSON or NDJSON exports backed by Postgres, which is the source of truth for delivery history.

​
Endpoints

  • GET /v1/delivery/events
  • GET /v1/delivery/events/export
Use the /v1/delivery/events namespace for delivery history so it does not collide with SEC event APIs such as enforcement, auditor-change, and voting-result routes.

​
Filtered event inspection

Useful filters:
  • kind
  • type
  • requestId
  • since
  • limit

​
Export JSON

​
Export NDJSON

Use NDJSON when downstream tooling wants line-oriented ingestion into log processors or ad hoc support scripts.

​
CLI

​
Job-completion webhooks (no polling)

Async jobs announce their terminal state as webhook events, so you no longer have to poll:
  • intelligence.query.completed / intelligence.query.failed — an async /v1/intelligence/query job finished.
  • export.completed / export.failed — an async bulk export finished and a signed download URL is available.
Subscribe by adding the type to a webhook endpoint’s subscribedEventTypes (see webhook-stream-workflows). Sample export.completed payload:

​
Verifying webhook signatures

Outbound webhooks are signed exactly like Stripe: an HMAC-SHA256 over ${timestamp}.${rawBody} using your endpoint’s signing secret, delivered in the signature header. Recompute the HMAC over the raw request body and compare in constant time before trusting a payload.

​
Bulk export → signed URL

For datasets too large to inline in a tool result, materialize them once to a short-lived signed download URL.
  • MCP tool exports.create — e.g. { "dataset": "company_overview", "tickers": ["AAPL","MSFT",…], "format": "csv", "idempotency_key": "portfolio-A" } returns an export_job with the downloadUrl (valid ~15 min) directly in the response, and also emits export.completed (for webhook subscribers / audit). Reusing the same idempotency_key returns the same file instead of regenerating. Bills per entity, like companies.overview.
  • MCP tool exports.get — re-sign the URL later with { "jobId": "exp_…", "format": "csv" }. Returns not-found for an unknown or expired job.

​
Operational notes

  • exports are tenant-scoped
  • request correlation is driven by Request-Id
  • support should prefer exports over direct database access for tenant-scoped delivery history
  • stream polling uses per-subscription delivery records, so re-reading the same cursor window does not create new billable delivery units
  • when Postgres is configured and the durable ledger cannot be read, the API returns delivery_ledger_unavailable with HTTP 503 rather than returning an empty history