Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.secapi.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
POST /v1/analytics/query

Run a tenant-safe analytical query over supported Datastream history datasets without exposing raw SQL
Audience: application and coding agent.

​
Supported datasets

DatasetDescriptionDimensionsMeasures
filingsSEC filing historyyear, form, tickercount
sections_itemsFiling section extractsyear, form, tickercount
segmented_revenuesXBRL segmented revenue datayear, tickercount, sum_value
ownershipInstitutional ownership filings (13F, 13D/G)year, form, tickercount
enforcementSEC enforcement actionsyear, source_typecount

​
Request body

FieldTypeRequiredDescription
datasetstringYesOne of filings, sections_items, segmented_revenues, ownership, enforcement
dimensionsstring[]Yes1-2 dimensions to group by: year, form, ticker, source_type
measuresstring[]NoAggregation measures: count (default), sum_value
filtersobjectNoFilter by ticker, cik, or form
timeWindowobjectNo{ from?: string, to?: string } date range filter
sortobjectNo{ field: string, direction?: "asc" | "desc" }
limitnumberNoMax rows returned (1-200, default 50)

​
Canonical metadata

  • requestId
  • traceparent
  • dataset
  • dimensions
  • filters
  • timeWindow
  • sort
  • rowCount
  • warnings
  • provenance

​
Example request

curl -X POST \
  -H "x-api-key: $OMNI_DATASTREAM_API_KEY" \
  -H "omni-version: 2026-03-19" \
  -H "content-type: application/json" \
  -d '{"dataset":"filings","dimensions":["year","form"],"filters":{"ticker":"AAPL"},"timeWindow":{"from":"2020-01-01","to":"2025-12-31"},"sort":{"field":"count","direction":"desc"},"limit":20}' \
  "https://api.secapi.ai/v1/analytics/query"

​
Example response

{
  "object": "analytics_query_result",
  "dataset": "filings",
  "dimensions": [
    "year",
    "form"
  ],
  "measures": [
    "count"
  ],
  "filters": {
    "ticker": "AAPL"
  },
  "timeWindow": {
    "from": "2020-01-01",
    "to": "2025-12-31"
  },
  "sort": {
    "field": "count",
    "direction": "desc"
  },
  "limit": 20,
  "rowCount": 3,
  "rows": [
    {
      "values": {
        "year": "2024",
        "form": "10-Q",
        "count": 3
      }
    },
    {
      "values": {
        "year": "2024",
        "form": "10-K",
        "count": 1
      }
    },
    {
      "values": {
        "year": "2023",
        "form": "10-K",
        "count": 1
      }
    }
  ],
  "requestId": "req_abc123",
  "traceparent": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-00"
}

​
Give this prompt to your agent

​
Failure posture

  • treat non-2xx responses as contract-aware failures, not free-form errors
  • preserve requestId and traceparent in logs and downstream reports
  • if provenance or freshness metadata is present, return it unchanged so trust is not lost in the handoff