> ## 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 SEC API history datasets without exposing raw SQL

Run a tenant-safe analytical query over supported SEC API history datasets without exposing raw SQL

<Info>
  Audience: application and coding agent.
</Info>

## Supported datasets

| Dataset              | Description                                  | Dimensions               | Measures             |
| -------------------- | -------------------------------------------- | ------------------------ | -------------------- |
| `filings`            | SEC filing history                           | `year`, `form`, `ticker` | `count`              |
| `sections_items`     | Filing section extracts                      | `year`, `form`, `ticker` | `count`              |
| `segmented_revenues` | XBRL segmented revenue data                  | `year`, `ticker`         | `count`, `sum_value` |
| `ownership`          | Institutional ownership filings (13F, 13D/G) | `year`, `form`, `ticker` | `count`              |
| `enforcement`        | SEC enforcement actions                      | `year`, `source_type`    | `count`              |

## Request body

| Field        | Type      | Required | Description                                                                          |
| ------------ | --------- | -------- | ------------------------------------------------------------------------------------ |
| `dataset`    | string    | Yes      | One of `filings`, `sections_items`, `segmented_revenues`, `ownership`, `enforcement` |
| `dimensions` | string\[] | Yes      | 1-2 dimensions to group by: `year`, `form`, `ticker`, `source_type`                  |
| `measures`   | string\[] | No       | Aggregation measures: `count` (default), `sum_value`                                 |
| `filters`    | object    | No       | Filter by `ticker`, `cik`, or `form`                                                 |
| `timeWindow` | object    | No       | `{ from?: string, to?: string }` date range filter                                   |
| `sort`       | object    | No       | `{ field: string, direction?: "asc" \| "desc" }`                                     |
| `limit`      | number    | No       | Max rows returned (1-200, default 50)                                                |

## Canonical metadata

* `requestId`
* `traceparent`
* `dataset`
* `dimensions`
* `filters`
* `timeWindow`
* `sort`
* `rowCount`
* `warnings`
* `provenance`

## Example request

<RequestExample>
  ```bash theme={null}
  curl -X POST \
    -H "x-api-key: $SECAPI_API_KEY" \
    -H "secapi-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"
  ```
</RequestExample>

## Example response

<ResponseExample>
  ```json theme={null}
  {
    "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_2ZK8Q1W9F4M6P7R3"
  }
  ```
</ResponseExample>

## Give this prompt to your agent

<Prompt>
  Use SEC API POST /v1/analytics/query to run a tenant-safe analytical query over supported SEC API history datasets without exposing raw SQL. Preserve `requestId`, `traceparent`, `dataset`, `dimensions`, `filters`, `timeWindow`, `sort`, `rowCount`, `warnings`, `provenance` in the output. Return a concise markdown summary plus the exact structured payload fields that a downstream engineer or agent should keep using this result.
</Prompt>

## 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