Skip to main content

​
POST /v1/analytics/query

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

​
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":"segmented_revenues","dimensions":["segmentType","year"],"measures":["count","sum_value"],"filters":{"ticker":"AAPL","period":"annual"},"timeWindow":{"field":"filingDate","from":"2024-01-01","to":"2025-12-31"},"sort":{"field":"sum_value","direction":"desc"},"limit":50}' \
  "https://api.secapi.ai/v1/analytics/query"

​
Example response

{
  "object": "analytics_query_result",
  "id": "aqr_example_123",
  "createdAt": "2026-03-19T18:00:00.000Z",
  "livemode": false,
  "dataset": "segmented_revenues",
  "mode": "aggregate",
  "dimensions": [
    "segmentType",
    "year"
  ],
  "measures": [
    "count",
    "sum_value"
  ],
  "filters": {
    "ticker": "AAPL",
    "period": "annual"
  },
  "timeWindow": {
    "field": "filingDate",
    "from": "2024-01-01",
    "to": "2025-12-31"
  },
  "sort": {
    "field": "sum_value",
    "direction": "desc"
  },
  "limit": 50,
  "rowCount": 2,
  "rows": [
    {
      "values": {
        "segmentType": "product",
        "year": 2025,
        "count": 4,
        "sum_value": 391035000000
      }
    },
    {
      "values": {
        "segmentType": "geographic",
        "year": 2025,
        "count": 3,
        "sum_value": 124500000000
      }
    }
  ],
  "warnings": [],
  "provenance": {
    "source": "omni_datastream",
    "accessionNumber": null,
    "filingUrl": "https://api.secapi.ai/v1/analytics/query",
    "acceptedAt": null,
    "retrievedAt": "2026-03-19T18:00:00.000Z",
    "parserVersion": "analytics-query@2026-03-19"
  },
  "requestId": "req_123",
  "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