> ## Documentation Index
> Fetch the complete documentation index at: https://docs.insighthread.com/llms.txt
> Use this file to discover all available pages before exploring further.

# GET /events — Retrieve Real-Time SEC Market Events

> Retrieve real-time market events from SEC filings. Supports filtering by ticker, event type, date range, and impact score. Includes single-event lookup.

The `/events` endpoint is the core of the Insighthread News API, returning real-time market events sourced from SEC EDGAR filings. Each event includes a structured headline, an AI-generated summary, the originating SEC filing reference, and a 5-bar impact signal — giving your integration everything it needs to act on material corporate developments without touching the raw filing.

## Endpoint

```
GET https://api.insighthread.com/v1/events
```

## Query Parameters

<ParamField query="ticker" type="string">
  Filter events to a single company by its ticker symbol. Case-insensitive. Example: `AAPL`, `NVDA`, `MSFT`.
</ParamField>

<ParamField query="event_type" type="string">
  Filter by event category. Must match a value from the [Event Categories](/api/event-categories) reference exactly. Example: `Mergers and Acquisitions`. URL-encode values containing spaces or slashes.
</ParamField>

<ParamField query="impact_min" type="integer">
  Return only events with an impact score at or above this threshold. Accepts integers `1` through `5`. For example, passing `4` returns only `Major` (4) and `Critical` (5) events. Omit to return all impact levels.
</ParamField>

<ParamField query="direction" type="string">
  Filter events by the direction of their impact signal. Accepted values: `positive`, `negative`, `neutral`.
</ParamField>

<ParamField query="from" type="string">
  Return only events published at or after this timestamp. Must be a valid ISO 8601 datetime string. Example: `2026-01-01T00:00:00Z`.
</ParamField>

<ParamField query="to" type="string">
  Return only events published at or before this timestamp. Must be a valid ISO 8601 datetime string. Use in combination with `from` to define a fixed time window.
</ParamField>

<ParamField query="limit" type="integer" default="20">
  Number of events to return per page. Default is `20`; maximum is `100`.
</ParamField>

<ParamField query="cursor" type="string">
  Pagination cursor returned in the `next_cursor` field of a previous response. Pass this value to retrieve the next page of results. Omit for the first request.
</ParamField>

## Example Request

The following request retrieves up to 5 high-impact events for NVDA with an impact score of 3 or above:

```bash theme={null}
curl "https://api.insighthread.com/v1/events?ticker=NVDA&impact_min=3&limit=5" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Example Response

```json theme={null}
{
  "data": [
    {
      "id": "evt_8k101_nvda_apr14",
      "ticker": "NVDA",
      "event_type": "Mergers and Acquisitions",
      "headline": "NVIDIA acquires Run:ai in $700M all-cash transaction",
      "summary": "NVIDIA Corporation has entered into a definitive agreement to acquire Run:ai, an AI workload management platform, for approximately $700 million in cash. The acquisition is expected to close in the second half of fiscal 2026, subject to regulatory approvals.",
      "primary_filing": "8-K (1.01)",
      "secondary_filing": null,
      "filing_url": "https://sec.gov/Archives/edgar/data/1045810/000104581026000041/0001045810-26-000041-index.htm",
      "impact": {
        "score": 4,
        "direction": "positive",
        "label": "Major",
        "bars": 4
      },
      "published_at": "2026-04-14T09:18:33Z"
    },
    {
      "id": "evt_8k103_iobt_mar31",
      "ticker": "IOBT",
      "event_type": "Bankruptcy/Liquidation",
      "headline": "IO Biotech files Chapter 7, ceases all operations",
      "summary": "IO Biotech has filed for Chapter 7 bankruptcy protection and will cease all operations immediately. The company's assets are to be liquidated under the supervision of a court-appointed trustee following the failure of its lead oncology program.",
      "primary_filing": "8-K (1.03)",
      "secondary_filing": "15-12B",
      "filing_url": "https://sec.gov/Archives/edgar/data/1834585/000183458526000008/0001834585-26-000008-index.htm",
      "impact": {
        "score": 5,
        "direction": "negative",
        "label": "Critical",
        "bars": 5
      },
      "published_at": "2026-03-31T14:22:08Z"
    }
  ],
  "next_cursor": "eyJpZCI6ImV2dF84azEwM19pb2J0X21hcjMxIiwiZGlyIjoibmV4dCJ9",
  "total": 47
}
```

## Response Fields

<ResponseField name="data" type="array">
  Array of event objects matching the query. May be empty if no events match the specified filters.

  <Expandable title="Event object fields">
    <ResponseField name="id" type="string">
      Unique identifier for the event. Format: `evt_{filing_type}_{ticker}_{date}`.
    </ResponseField>

    <ResponseField name="ticker" type="string">
      Ticker symbol of the company associated with this event.
    </ResponseField>

    <ResponseField name="event_type" type="string">
      Event category. One of 35+ possible values. See the [Event Categories](/api/event-categories) reference for the complete list.
    </ResponseField>

    <ResponseField name="headline" type="string">
      Short, human-readable headline summarizing the event in a single sentence.
    </ResponseField>

    <ResponseField name="summary" type="string">
      AI-generated summary of the event, typically 1–3 sentences. Grounded in the content of the SEC filing.
    </ResponseField>

    <ResponseField name="primary_filing" type="string">
      The primary SEC filing type and item section that triggered this event. Example: `8-K (1.01)`, `10-Q`, `Form 4`.
    </ResponseField>

    <ResponseField name="secondary_filing" type="string | null">
      A secondary SEC filing associated with the same event, if applicable. `null` if there is no secondary filing.
    </ResponseField>

    <ResponseField name="filing_url" type="string">
      Direct URL to the original filing on SEC EDGAR. Use this to link users to the primary source.
    </ResponseField>

    <ResponseField name="impact" type="object">
      Impact signal for this event. Contains a score, directional label, and human-readable severity label.

      <Expandable title="impact fields">
        <ResponseField name="impact.score" type="integer">
          Numerical impact score from `1` (Minor) to `5` (Critical). Maps directly to `bars`.
        </ResponseField>

        <ResponseField name="impact.direction" type="string">
          Directional assessment of the event's impact: `positive`, `negative`, or `neutral`.
        </ResponseField>

        <ResponseField name="impact.label" type="string">
          Human-readable severity label corresponding to the score: `Minor`, `Moderate`, `Significant`, `Major`, or `Critical`.
        </ResponseField>

        <ResponseField name="impact.bars" type="integer">
          Visual bar count from `1` to `5`, identical to `score`. Maps to the 5-bar impact indicator in the Insighthread UI.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="published_at" type="string">
      ISO 8601 timestamp indicating when Insighthread published this event, within 90 seconds of the SEC filing being accepted by EDGAR.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="next_cursor" type="string | null">
  Opaque pagination cursor pointing to the next page of results. Pass this value as the `cursor` query parameter on your next request. Returns `null` when the current page is the last page.
</ResponseField>

<ResponseField name="total" type="integer">
  Total number of events matching the query across all pages.
</ResponseField>

## Get a Single Event

Retrieve a single event by its unique identifier. Use this endpoint to refresh or re-fetch a specific event after you have already stored its `id`.

```
GET https://api.insighthread.com/v1/events/{id}
```

### Path Parameters

<ParamField path="id" type="string" required>
  The unique event identifier. Obtained from the `id` field of any event object returned by `GET /events` or `GET /companies/{ticker}`. Example: `evt_8k101_nvda_apr14`.
</ParamField>

### Example Request

```bash theme={null}
curl "https://api.insighthread.com/v1/events/evt_8k101_nvda_apr14" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Example Response

```json theme={null}
{
  "id": "evt_8k101_nvda_apr14",
  "ticker": "NVDA",
  "event_type": "Mergers and Acquisitions",
  "headline": "NVIDIA acquires Run:ai in $700M all-cash transaction",
  "summary": "NVIDIA Corporation has entered into a definitive agreement to acquire Run:ai, an AI workload management platform, for approximately $700 million in cash. The acquisition is expected to close in the second half of fiscal 2026, subject to regulatory approvals.",
  "primary_filing": "8-K (1.01)",
  "secondary_filing": null,
  "filing_url": "https://sec.gov/Archives/edgar/data/1045810/000104581026000041/0001045810-26-000041-index.htm",
  "impact": {
    "score": 4,
    "direction": "positive",
    "label": "Major",
    "bars": 4
  },
  "published_at": "2026-04-14T09:18:33Z"
}
```

The single-event response returns the full Event object directly (not wrapped in a `data` array). All fields are identical to those described in the [Response Fields](#response-fields) section above. A `404 Not Found` is returned if the `id` does not exist.

## Pagination

The `/events` endpoint uses cursor-based pagination. When a response contains more results than the requested `limit`, the `next_cursor` field will be a non-null string. Pass that value as the `cursor` query parameter on your next request to retrieve the following page:

```bash theme={null}
# First request — no cursor
curl "https://api.insighthread.com/v1/events?limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Subsequent request — pass next_cursor from the previous response
curl "https://api.insighthread.com/v1/events?limit=20&cursor=eyJpZCI6ImV2dF84azEwM19pb2J0X21hcjMxIiwiZGlyIjoibmV4dCJ9" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

When `next_cursor` is `null`, you have reached the last page of results. Cursors are stable for the lifetime of a query — the same cursor will always return the same next page for the same set of filters.

<Note>
  Rate limits vary by enterprise plan tier. Contact your account manager to confirm your request-per-minute and daily limits. If you exceed your limit, the API returns `429 Too Many Requests` — implement exponential backoff before retrying.
</Note>


## Related topics

- [Insighthread News API: Real-Time SEC Event Intelligence](/api/overview.md)
- [Insighthread News Feed: Real-Time SEC Filing Events](/features/news-feed.md)
- [Real-Time SEC Filings Feed for All Public Companies](/features/sec-filings.md)
- [Monitor Market-Moving Events in Your Insighthread Feed](/guides/monitor-events.md)
- [Set Up Insighthread Event Alerts and Notifications](/account/notifications.md)